/ Hex Artifact Content
Login

Artifact 6804670ea1dab160100780a356843dc09a2ab36d:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20  r changes if.** 
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29  cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69   $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 33 34 37 20 32 30 30 38 2f 30  n,v 1.347 2008/0
05f0: 36 2f 32 31 20 31 38 3a 30 32 3a 31 37 20 6d 69  6/21 18:02:17 mi
0600: 68 61 69 6c 69 6d 20 45 78 70 20 24 0a 2a 2f 0a  hailim Exp $.*/.
0610: 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33  #ifndef _SQLITE3
0620: 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c  _H_.#define _SQL
0630: 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65  ITE3_H_.#include
0640: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0650: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0660: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0670: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0680: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0690: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
06a0: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
06b0: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
06c0: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
06d0: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41  #endif.../*.** A
06e0: 64 64 20 74 68 65 20 61 62 69 6c 69 74 79 20 74  dd the ability t
06f0: 6f 20 6f 76 65 72 72 69 64 65 20 27 65 78 74 65  o override 'exte
0700: 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  rn'.*/.#ifndef S
0710: 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64  QLITE_EXTERN.# d
0720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54  efine SQLITE_EXT
0730: 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69  ERN extern.#endi
0740: 66 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20  f../*.** Ensure 
0750: 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65  these symbols we
0760: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62  re not defined b
0770: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20  y some previous 
0780: 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a  header file..*/.
0790: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45  #ifdef SQLITE_VE
07a0: 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51  RSION.# undef SQ
07b0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e  LITE_VERSION.#en
07c0: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54  dif.#ifdef SQLIT
07d0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
07e0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
07f0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0800: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
0810: 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
0820: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
0830: 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 46 31 30  ion Numbers {F10
0840: 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  010}.**.** The S
0850: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 61 6e  QLITE_VERSION an
0860: 64 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  d SQLITE_VERSION
0870: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 73  _NUMBER #defines
0880: 20 69 6e 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74   in.** the sqlit
0890: 65 33 2e 68 20 66 69 6c 65 20 73 70 65 63 69 66  e3.h file specif
08a0: 79 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f 66  y the version of
08b0: 20 53 51 4c 69 74 65 20 77 69 74 68 20 77 68 69   SQLite with whi
08c0: 63 68 0a 2a 2a 20 74 68 61 74 20 68 65 61 64 65  ch.** that heade
08d0: 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63 69  r file is associ
08e0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
08f0: 22 76 65 72 73 69 6f 6e 22 20 6f 66 20 53 51 4c  "version" of SQL
0900: 69 74 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  ite is a string 
0910: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 58 2e 59  of the form "X.Y
0920: 2e 5a 22 2e 0a 2a 2a 20 54 68 65 20 70 68 72 61  .Z"..** The phra
0930: 73 65 20 22 61 6c 70 68 61 22 20 6f 72 20 22 62  se "alpha" or "b
0940: 65 74 61 22 20 6d 69 67 68 74 20 62 65 20 61 70  eta" might be ap
0950: 70 65 6e 64 65 64 20 61 66 74 65 72 20 74 68 65  pended after the
0960: 20 5a 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c   Z..** The X val
0970: 75 65 20 69 73 20 6d 61 6a 6f 72 20 76 65 72 73  ue is major vers
0980: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6c 77 61 79  ion number alway
0990: 73 20 33 20 69 6e 20 53 51 4c 69 74 65 33 2e 0a  s 3 in SQLite3..
09a0: 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 6f  ** The X value o
09b0: 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e  nly changes when
09c0: 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
09d0: 74 69 62 69 6c 69 74 79 20 69 73 0a 2a 2a 20 62  tibility is.** b
09e0: 72 6f 6b 65 6e 20 61 6e 64 20 77 65 20 69 6e 74  roken and we int
09f0: 65 6e 64 20 74 6f 20 6e 65 76 65 72 20 62 72 65  end to never bre
0a00: 61 6b 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ak backwards com
0a10: 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 54  patibility..** T
0a20: 68 65 20 59 20 76 61 6c 75 65 20 69 73 20 74 68  he Y value is th
0a30: 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20  e minor version 
0a40: 6e 75 6d 62 65 72 20 61 6e 64 20 6f 6e 6c 79 20  number and only 
0a50: 63 68 61 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20  changes when.** 
0a60: 74 68 65 72 65 20 61 72 65 20 6d 61 6a 6f 72 20  there are major 
0a70: 66 65 61 74 75 72 65 20 65 6e 68 61 6e 63 65 6d  feature enhancem
0a80: 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 66 6f  ents that are fo
0a90: 72 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c  rwards compatibl
0aa0: 65 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 62 61 63  e.** but not bac
0ab0: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c  kwards compatibl
0ac0: 65 2e 0a 2a 2a 20 54 68 65 20 5a 20 76 61 6c 75  e..** The Z valu
0ad0: 65 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65  e is the release
0ae0: 20 6e 75 6d 62 65 72 20 61 6e 64 20 69 73 20 69   number and is i
0af0: 6e 63 72 65 6d 65 6e 74 65 64 20 77 69 74 68 0a  ncremented with.
0b00: 2a 2a 20 65 61 63 68 20 72 65 6c 65 61 73 65 20  ** each release 
0b10: 62 75 74 20 72 65 73 65 74 73 20 62 61 63 6b 20  but resets back 
0b20: 74 6f 20 30 20 77 68 65 6e 65 76 65 72 20 59 20  to 0 whenever Y 
0b30: 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e 0a  is incremented..
0b40: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
0b50: 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  [sqlite3_libvers
0b60: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
0b70: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
0b80: 75 6d 62 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  umber()]..**.** 
0b90: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
0ba0: 2a 20 7b 46 31 30 30 31 31 7d 20 54 68 65 20 53  * {F10011} The S
0bb0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 23 64  QLITE_VERSION #d
0bc0: 65 66 69 6e 65 20 69 6e 20 74 68 65 20 73 71 6c  efine in the sql
0bd0: 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 69  ite3.h header fi
0be0: 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  le.**          e
0bf0: 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74  valuates to a st
0c00: 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61  ring literal tha
0c10: 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 20  t is the SQLite 
0c20: 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  version.**      
0c30: 20 20 20 20 77 69 74 68 20 77 68 69 63 68 20 74      with which t
0c40: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 69  he header file i
0c50: 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a  s associated..**
0c60: 0a 2a 2a 20 7b 46 31 30 30 31 34 7d 20 54 68 65  .** {F10014} The
0c70: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
0c80: 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 20 72  NUMBER #define r
0c90: 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e  esolves to an in
0ca0: 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
0cb0: 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65    with the value
0cc0: 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a   (X*1000000 + Y*
0cd0: 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20  1000 + Z) where 
0ce0: 58 2c 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20 20  X, Y, and Z.**  
0cf0: 20 20 20 20 20 20 20 20 61 72 65 20 74 68 65 20          are the 
0d00: 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20 6d  major version, m
0d10: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61 6e  inor version, an
0d20: 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72  d release number
0d30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
0d40: 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20  ITE_VERSION     
0d50: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
0d60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0d70: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d 2d  RSION_NUMBER  --
0d80: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
0d90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0da0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
0db0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0dc0: 72 73 20 7b 46 31 30 30 32 30 7d 0a 2a 2a 20 4b  rs {F10020}.** K
0dd0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
0de0: 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54  _version.**.** T
0df0: 68 65 73 65 20 66 65 61 74 75 72 65 73 20 70 72  hese features pr
0e00: 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69  ovide the same i
0e10: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68  nformation as th
0e20: 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  e [SQLITE_VERSIO
0e30: 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54  N].** and [SQLIT
0e40: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0e50: 5d 20 23 64 65 66 69 6e 65 73 20 69 6e 20 74 68  ] #defines in th
0e60: 65 20 68 65 61 64 65 72 2c 20 62 75 74 20 61 72  e header, but ar
0e70: 65 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  e associated.** 
0e80: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
0e90: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
0ea0: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 43 61  header file.  Ca
0eb0: 75 74 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d 65  utious programme
0ec0: 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 6c  rs might.** incl
0ed0: 75 64 65 20 61 20 63 68 65 63 6b 20 69 6e 20 74  ude a check in t
0ee0: 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  heir application
0ef0: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 0a   to verify that.
0f00: 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  ** sqlite3_libve
0f10: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 61  rsion_number() a
0f20: 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
0f30: 65 20 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49  e value.** [SQLI
0f40: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0f50: 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  R]..**.** The sq
0f60: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f70: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
0f80: 72 6e 73 20 74 68 65 20 73 61 6d 65 20 69 6e 66  rns the same inf
0f90: 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a 2a  ormation as is.*
0fa0: 2a 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  * in the sqlite3
0fb0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
0fc0: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
0fd0: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f   function is pro
0fe0: 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 65  vided.** for use
0ff0: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44   in DLLs since D
1000: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79  LL users usually
1010: 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 72   do not have dir
1020: 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74  ect access to st
1030: 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74  ring.** constant
1040: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c  s within the DLL
1050: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1060: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30 32  TS:.**.** {F1002
1070: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1080: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
1090: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
10a0: 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
10b0: 20 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71     an integer eq
10c0: 75 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 56  ual to [SQLITE_V
10d0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a  ERSION_NUMBER]..
10e0: 2a 2a 0a 2a 2a 20 7b 46 31 30 30 32 32 7d 20 54  **.** {F10022} T
10f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73  he [sqlite3_vers
1100: 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  ion] string cons
1110: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  tant contains.**
1120: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74 65            the te
1130: 78 74 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  xt of the [SQLIT
1140: 45 5f 56 45 52 53 49 4f 4e 5d 20 73 74 72 69 6e  E_VERSION] strin
1150: 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30 32 33  g..**.** {F10023
1160: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  } The [sqlite3_l
1170: 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 66 75 6e  ibversion()] fun
1180: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a 2a  ction returns.**
1190: 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e            a poin
11a0: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
11b0: 74 65 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72  te3_version] str
11c0: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 0a 2a 2f  ing constant..*/
11d0: 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
11e0: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65  onst char sqlite
11f0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e  3_version[];.con
1200: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1210: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64  _libversion(void
1220: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
1230: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1240: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1250: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f  API3REF: Test To
1260: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72   See If The Libr
1270: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66  ary Is Threadsaf
1280: 65 20 7b 46 31 30 31 30 30 7d 0a 2a 2a 0a 2a 2a  e {F10100}.**.**
1290: 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63   SQLite can be c
12a0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20  ompiled with or 
12b0: 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e  without mutexes.
12c0: 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 53 51    When.** the SQ
12d0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12e0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
12f0: 61 63 72 6f 20 69 73 20 74 72 75 65 2c 20 6d 75  acro is true, mu
1300: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
1310: 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20  bled and SQLite 
1320: 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  is threadsafe.  
1330: 57 68 65 6e 20 74 68 61 74 20 6d 61 63 72 6f 20  When that macro 
1340: 69 73 20 66 61 6c 73 65 2c 0a 2a 2a 20 74 68 65  is false,.** the
1350: 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69   mutexes are omi
1360: 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74  tted.  Without t
1370: 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69  he mutexes, it i
1380: 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f  s not safe.** to
1390: 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63   use SQLite conc
13a0: 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f  urrently from mo
13b0: 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65  re than one thre
13c0: 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69  ad..**.** Enabli
13d0: 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72  ng mutexes incur
13e0: 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70  s a measurable p
13f0: 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c  erformance penal
1400: 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65  ty..** So if spe
1410: 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20  ed is of utmost 
1420: 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d  importance, it m
1430: 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69  akes sense to di
1440: 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74  sable.** the mut
1450: 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d  exes.  But for m
1460: 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d  aximum safety, m
1470: 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65  utexes should be
1480: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65   enabled..** The
1490: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
14a0: 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73  r is for mutexes
14b0: 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a   to be enabled..
14c0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
14d0: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
14e0: 20 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f   by a program to
14f0: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20   make sure that 
1500: 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f  the.** version o
1510: 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74  f SQLite that it
1520: 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69   is linking agai
1530: 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  nst was compiled
1540: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73   with.** the des
1550: 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20  ired setting of 
1560: 74 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41  the SQLITE_THREA
1570: 44 53 41 46 45 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  DSAFE macro..**.
1580: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1590: 2a 0a 2a 2a 20 7b 46 31 30 31 30 31 7d 20 54 68  *.** {F10101} Th
15a0: 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  e [sqlite3_threa
15b0: 64 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f  dsafe()] functio
15c0: 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 7a 65 72  n returns nonzer
15d0: 6f 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  o if.**         
15e0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
15f0: 69 6c 65 64 20 77 69 74 68 20 69 74 73 20 6d 75  iled with its mu
1600: 74 65 78 65 73 20 65 6e 61 62 6c 65 64 20 6f 72  texes enabled or
1610: 20 7a 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20 20   zero.**        
1620: 20 20 69 66 20 53 51 4c 69 74 65 20 77 61 73 20    if SQLite was 
1630: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1640: 74 65 78 65 73 20 64 69 73 61 62 6c 65 64 2e 0a  texes disabled..
1650: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
1660: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b  hreadsafe(void);
1670: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1680: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
1690: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 46 31  ction Handle {F1
16a0: 32 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  2000}.** KEYWORD
16b0: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
16c0: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
16d0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
16e0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
16f0: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
1700: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
1710: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  y a pointer to a
1720: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a  n instance of.**
1730: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75   the opaque stru
1740: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c  cture named "sql
1750: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73  ite3".  It is us
1760: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66  eful to think of
1770: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70   an sqlite3.** p
1780: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a  ointer as an obj
1790: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ect.  The [sqlit
17a0: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
17b0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
17c0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
17d0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
17e0: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f  faces are its co
17f0: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20  nstructors, and 
1800: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1810: 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74  ].** is its dest
1820: 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61  ructor.  There a
1830: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e  re many other in
1840: 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61  terfaces (such a
1850: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  s.** [sqlite3_pr
1860: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
1870: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
1880: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a  ction()], and.**
1890: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
18a0: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d  imeout()] to nam
18b0: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61  e but three) tha
18c0: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e  t are methods on
18d0: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f   an.** sqlite3 o
18e0: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65  bject..*/.typede
18f0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
1900: 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a   sqlite3;../*.**
1910: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
1920: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20  t Integer Types 
1930: 7b 46 31 30 32 30 30 7d 0a 2a 2a 20 4b 45 59 57  {F10200}.** KEYW
1940: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
1950: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
1960: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1970: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
1980: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
1990: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
19a0: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
19b0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
19c0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
19d0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
19e0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
19f0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
1a00: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
1a10: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
1a20: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
1a30: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
1a40: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
1a50: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
1a60: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
1a70: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
1a80: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
1a90: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
1aa0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1ab0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 30 31  S:.**.** {F10201
1ac0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 69 6e  } The [sqlite_in
1ad0: 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  t64] and [sqlite
1ae0: 33 5f 69 6e 74 36 34 5d 20 74 79 70 65 73 20 73  3_int64] types s
1af0: 70 65 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20  pecify.**       
1b00: 20 20 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e     a 64-bit sign
1b10: 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  ed integer..**.*
1b20: 2a 20 7b 46 31 30 32 30 32 7d 20 54 68 65 20 5b  * {F10202} The [
1b30: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20 61  sqlite_uint64] a
1b40: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74  nd [sqlite3_uint
1b50: 36 34 5d 20 74 79 70 65 73 20 73 70 65 63 69 66  64] types specif
1b60: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  y.**          a 
1b70: 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  64-bit unsigned 
1b80: 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66 64  integer..*/.#ifd
1b90: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
1ba0: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
1bb0: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
1bc0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
1bd0: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
1be0: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
1bf0: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
1c00: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
1c10: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
1c20: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
1c30: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
1c40: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
1c50: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
1c60: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
1c70: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
1c80: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
1c90: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
1ca0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
1cb0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
1cc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
1cd0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
1ce0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
1cf0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
1d00: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
1d10: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
1d20: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
1d30: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
1d40: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
1d50: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
1d60: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
1d70: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
1d80: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
1d90: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
1da0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
1db0: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
1dc0: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
1dd0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
1de0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1df0: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
1e00: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1e10: 74 69 6f 6e 20 7b 46 31 32 30 31 30 7d 0a 2a 2a  tion {F12010}.**
1e20: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1e30: 20 69 73 20 74 68 65 20 64 65 73 74 72 75 63 74   is the destruct
1e40: 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  or for the [sqli
1e50: 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  te3] object..**.
1e60: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
1e70: 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f  should [sqlite3_
1e80: 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
1e90: 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72  ize] all [prepar
1ea0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a  ed statements].*
1eb0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  * and [sqlite3_b
1ec0: 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73  lob_close | clos
1ed0: 65 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  e] all [sqlite3_
1ee0: 62 6c 6f 62 20 7c 20 42 4c 4f 42 73 5d 20 61 73  blob | BLOBs] as
1ef0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
1f00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
1f10: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
1f20: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
1f30: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a  se the object..*
1f40: 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e  * The [sqlite3_n
1f50: 65 78 74 5f 73 74 6d 74 28 29 5d 20 69 6e 74 65  ext_stmt()] inte
1f60: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1f70: 64 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 0a  d to locate all.
1f80: 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1f90: 74 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69 61  tements] associa
1fa0: 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
1fb0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1fc0: 20 69 66 20 64 65 73 69 72 65 64 2e 0a 2a 2a 20   if desired..** 
1fd0: 54 79 70 69 63 61 6c 20 63 6f 64 65 20 6d 69 67  Typical code mig
1fe0: 68 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 69  ht look like thi
1ff0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
2000: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71  uote><pre>.** sq
2010: 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2020: 74 3b 0a 2a 2a 20 77 68 69 6c 65 28 20 28 70 53  t;.** while( (pS
2030: 74 6d 74 20 3d 20 73 71 6c 69 74 65 33 5f 6e 65  tmt = sqlite3_ne
2040: 78 74 5f 73 74 6d 74 28 64 62 2c 20 30 29 29 21  xt_stmt(db, 0))!
2050: 3d 30 20 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20  =0 ){.** &nbsp; 
2060: 20 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69    sqlite3_finali
2070: 7a 65 28 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a  ze(pStmt);.** }.
2080: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
2090: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20  quote>.**.** If 
20a0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
20b0: 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 69  ] is invoked whi
20c0: 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  le a transaction
20d0: 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65   is open,.** the
20e0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
20f0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
2100: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
2110: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2120: 2a 2a 20 7b 46 31 32 30 31 31 7d 20 54 68 65 20  ** {F12011} The 
2130: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
2140: 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73 74  ] interface dest
2150: 72 6f 79 73 20 61 6e 20 5b 73 71 6c 69 74 65 33  roys an [sqlite3
2160: 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20  ] object.**     
2170: 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62       allocated b
2180: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
2190: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
21a0: 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
21b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
21c0: 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
21d0: 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  open_v2()]..**.*
21e0: 2a 20 7b 46 31 32 30 31 32 7d 20 54 68 65 20 5b  * {F12012} The [
21f0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
2200: 20 66 75 6e 63 74 69 6f 6e 20 72 65 6c 65 61 73   function releas
2210: 65 73 20 61 6c 6c 20 6d 65 6d 6f 72 79 20 75 73  es all memory us
2220: 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
2230: 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e        connection
2240: 20 61 6e 64 20 63 6c 6f 73 65 73 20 61 6c 6c 20   and closes all 
2250: 6f 70 65 6e 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a  open files..**.*
2260: 2a 20 7b 46 31 32 30 31 33 7d 20 49 66 20 74 68  * {F12013} If th
2270: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2280: 63 74 69 6f 6e 20 63 6f 6e 74 61 69 6e 73 20 5b  ction contains [
2290: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22a0: 6e 74 73 5d 20 74 68 61 74 0a 2a 2a 20 20 20 20  nts] that.**    
22b0: 20 20 20 20 20 20 68 61 76 65 20 6e 6f 74 20 62        have not b
22c0: 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
22d0: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
22e0: 64 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d],.**          
22f0: 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6c  then [sqlite3_cl
2300: 6f 73 65 28 29 5d 20 72 65 74 75 72 6e 73 20 5b  ose()] returns [
2310: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
2320: 20 6c 65 61 76 65 73 0a 2a 2a 20 20 20 20 20 20   leaves.**      
2330: 20 20 20 20 74 68 65 20 63 6f 6e 6e 65 63 74 69      the connecti
2340: 6f 6e 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  on open..**.** {
2350: 46 31 32 30 31 34 7d 20 50 61 73 73 69 6e 67 20  F12014} Passing 
2360: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2370: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2380: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
2390: 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  op..**.** {F1201
23a0: 39 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  9} When [sqlite3
23b0: 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76  _close()] is inv
23c0: 6f 6b 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62  oked on a [datab
23d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
23e0: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
23f0: 20 68 61 73 20 61 20 70 65 6e 64 69 6e 67 20 74   has a pending t
2400: 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 20  ransaction, the 
2410: 74 72 61 6e 73 61 63 74 69 6f 6e 20 73 68 61 6c  transaction shal
2420: 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  l be.**         
2430: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
2440: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
2450: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 30 31 35 7d 20  .**.** {U12015} 
2460: 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  The parameter to
2470: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2480: 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 5b 73  )] must be an [s
2490: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 0a 2a  qlite3] object.*
24a0: 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
24b0: 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  er previously ob
24c0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
24d0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
24e0: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
24f0: 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 4e  equivalent, or N
2500: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 30  ULL..**.** {U120
2510: 31 36 7d 20 54 68 65 20 70 61 72 61 6d 65 74 65  16} The paramete
2520: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  r to [sqlite3_cl
2530: 6f 73 65 28 29 5d 20 6d 75 73 74 20 6e 6f 74 20  ose()] must not 
2540: 68 61 76 65 20 62 65 65 6e 20 70 72 65 76 69 6f  have been previo
2550: 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  usly.**         
2560: 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20   closed..*/.int 
2570: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71  sqlite3_close(sq
2580: 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  lite3 *);../*.**
2590: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
25a0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
25b0: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
25c0: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
25d0: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
25e0: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
25f0: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
2600: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
2610: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
2620: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
2630: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
2640: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
2650: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
2660: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
2670: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
2680: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 7b 46  ion Interface {F
2690: 31 32 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12100}.**.** The
26a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
26b0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
26c0: 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f 66  onvenient way of
26d0: 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20   running one or 
26e0: 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74  more.** SQL stat
26f0: 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20 68  ements without h
2700: 61 76 69 6e 67 20 74 6f 20 77 72 69 74 65 20 61  aving to write a
2710: 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20   lot of C code. 
2720: 20 54 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   The UTF-8 encod
2730: 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
2740: 65 6e 74 73 20 61 72 65 20 70 61 73 73 65 64 20  ents are passed 
2750: 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  in as the second
2760: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2770: 6c 69 74 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a  lite3_exec()..**
2780: 20 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20   The statements 
2790: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 6f 6e  are evaluated on
27a0: 65 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65  e by one until e
27b0: 69 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f  ither an error o
27c0: 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 75 70  r.** an interrup
27d0: 74 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65 64  t is encountered
27e0: 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 79 20  , or until they 
27f0: 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54  are all done.  T
2800: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2810: 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e  .** is an option
2820: 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74  al callback that
2830: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
2840: 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66   for each row of
2850: 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20 72 65   any query.** re
2860: 73 75 6c 74 73 20 70 72 6f 64 75 63 65 64 20 62  sults produced b
2870: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
2880: 65 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20 70  ents.  The 5th p
2890: 61 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77  arameter tells w
28a0: 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65  here.** to write
28b0: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
28c0: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65  ges..**.** The e
28d0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61 73  rror message pas
28e0: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68  sed back through
28f0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
2900: 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e  er is held.** in
2910: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
2920: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2930: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76  alloc()].  To av
2940: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
2950: 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e  k,.** the callin
2960: 67 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  g application sh
2970: 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74  ould call [sqlit
2980: 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e  e3_free()] on an
2990: 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  y error.** messa
29a0: 67 65 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  ge returned thro
29b0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
29c0: 6d 65 74 65 72 20 77 68 65 6e 20 69 74 20 68 61  meter when it ha
29d0: 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
29e0: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
29f0: 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ssage..**.** If 
2a00: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2a10: 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72  t in the 2nd par
2a20: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f  ameter is NULL o
2a30: 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
2a40: 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e 67  g.** or a string
2a50: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79   containing only
2a60: 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 20   whitespace and 
2a70: 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e  comments, then n
2a80: 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  o SQL.** stateme
2a90: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
2aa0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
2ab0: 73 65 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  se is not change
2ac0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
2ad0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
2ae0: 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
2af0: 6e 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f 66  nted in terms of
2b00: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2b10: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
2b20: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e  ite3_step()], an
2b30: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2b40: 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  ize()]..** The s
2b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72 6f  qlite3_exec() ro
2b60: 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69  utine does nothi
2b70: 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ng to the databa
2b80: 73 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  se that cannot b
2b90: 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71  e done.** by [sq
2ba0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2bb0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2bc0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2bd0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
2be0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2bf0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 31  S:.**.** {F12101
2c00: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
2c10: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
2c20: 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43  lite3_exec(D,S,C
2c30: 2c 41 2c 45 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,A,E)].**       
2c40: 20 20 20 73 68 61 6c 6c 20 65 76 61 6c 75 61 74     shall evaluat
2c50: 65 20 61 6c 6c 20 6f 66 20 74 68 65 20 55 54 46  e all of the UTF
2c60: 2d 38 20 65 6e 63 6f 64 65 64 2c 20 73 65 6d 69  -8 encoded, semi
2c70: 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 0a  colon-separated.
2c80: 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20  **          SQL 
2c90: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
2ca0: 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
2cb0: 64 20 73 74 72 69 6e 67 20 53 20 77 69 74 68 69  d string S withi
2cc0: 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
2cd0: 20 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65    context of the
2ce0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2cf0: 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
2d00: 7b 46 31 32 31 30 32 7d 20 49 66 20 74 68 65 20  {F12102} If the 
2d10: 53 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  S parameter to [
2d20: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53  sqlite3_exec(D,S
2d30: 2c 43 2c 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c  ,C,A,E)] is NULL
2d40: 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
2d50: 20 20 74 68 65 20 61 63 74 69 6f 6e 73 20 6f 66    the actions of
2d60: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 73   the interface s
2d70: 68 61 6c 6c 20 62 65 20 74 68 65 20 73 61 6d 65  hall be the same
2d80: 20 61 73 20 69 66 20 74 68 65 0a 2a 2a 20 20 20   as if the.**   
2d90: 20 20 20 20 20 20 20 53 20 70 61 72 61 6d 65 74         S paramet
2da0: 65 72 20 77 65 72 65 20 61 6e 20 65 6d 70 74 79  er were an empty
2db0: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
2dc0: 46 31 32 31 30 34 7d 20 54 68 65 20 72 65 74 75  F12104} The retu
2dd0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  rn value of [sql
2de0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61  ite3_exec()] sha
2df0: 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 4f 4b  ll be [SQLITE_OK
2e00: 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  ] if all.**     
2e10: 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
2e20: 6e 74 73 20 72 75 6e 20 73 75 63 63 65 73 73 66  nts run successf
2e30: 75 6c 6c 79 20 61 6e 64 20 74 6f 20 63 6f 6d 70  ully and to comp
2e40: 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  letion..**.** {F
2e50: 31 32 31 30 35 7d 20 54 68 65 20 72 65 74 75 72  12105} The retur
2e60: 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  n value of [sqli
2e70: 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c  te3_exec()] shal
2e80: 6c 20 62 65 20 61 6e 20 61 70 70 72 6f 70 72 69  l be an appropri
2e90: 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ate.**          
2ea0: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
2eb0: 63 6f 64 65 5d 20 69 66 20 61 6e 79 20 53 51 4c  code] if any SQL
2ec0: 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 73   statement fails
2ed0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 37 7d  ..**.** {F12107}
2ee0: 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   If one or more 
2ef0: 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  of the SQL state
2f00: 6d 65 6e 74 73 20 68 61 6e 64 65 64 20 74 6f 20  ments handed to 
2f10: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2f20: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2f30: 75 72 6e 20 72 65 73 75 6c 74 73 20 61 6e 64 20  urn results and 
2f40: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
2f50: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  r is not NULL, t
2f60: 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
2f70: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
2f80: 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20  ction specified 
2f90: 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  by the 3rd param
2fa0: 65 74 65 72 20 73 68 61 6c 6c 20 62 65 0a 2a 2a  eter shall be.**
2fb0: 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 6b 65            invoke
2fc0: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
2fd0: 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a  row of result..*
2fe0: 2a 0a 2a 2a 20 7b 46 31 32 31 31 30 7d 20 49 66  *.** {F12110} If
2ff0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
3000: 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
3010: 20 76 61 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c   value then [sql
3020: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
3030: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 61           shall a
3040: 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
3050: 74 65 6d 65 6e 74 20 69 74 20 69 73 20 63 75 72  tement it is cur
3060: 72 65 6e 74 6c 79 20 65 76 61 6c 75 61 74 69 6e  rently evaluatin
3070: 67 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  g,.**          s
3080: 6b 69 70 20 61 6c 6c 20 73 75 62 73 65 71 75 65  kip all subseque
3090: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
30a0: 73 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  s, and return [S
30b0: 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
30c0: 0a 2a 2a 20 7b 46 31 32 31 31 33 7d 20 54 68 65  .** {F12113} The
30d0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
30e0: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
30f0: 70 61 73 73 20 69 74 73 20 34 74 68 20 70 61 72  pass its 4th par
3100: 61 6d 65 74 65 72 20 74 68 72 6f 75 67 68 0a 2a  ameter through.*
3110: 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68  *          as th
3120: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3130: 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  of the callback.
3140: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 36 7d 20  .**.** {F12116} 
3150: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
3160: 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 65 74  c()] routine set
3170: 73 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  s the 2nd parame
3180: 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20  ter of its.**   
3190: 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
31a0: 74 6f 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72  to be the number
31b0: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
31c0: 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
31d0: 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  f.**          re
31e0: 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  sult..**.** {F12
31f0: 31 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  119} The [sqlite
3200: 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e  3_exec()] routin
3210: 65 20 73 65 74 73 20 74 68 65 20 33 72 64 20 70  e sets the 3rd p
3220: 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a  arameter of its.
3230: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
3240: 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72  back to be an ar
3250: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3260: 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69  to strings holdi
3270: 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ng the.**       
3280: 20 20 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61     values for ea
3290: 63 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  ch column in the
32a0: 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20   current result 
32b0: 73 65 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20  set row as.**   
32c0: 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20         obtained 
32d0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
32e0: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
32f0: 0a 2a 2a 20 7b 46 31 32 31 32 32 7d 20 54 68 65  .** {F12122} The
3300: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3310: 5d 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74  ] routine sets t
3320: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
3330: 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20   of its.**      
3340: 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20      callback to 
3350: 62 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  be an array of p
3360: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3370: 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a  gs holding the.*
3380: 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73  *          names
3390: 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
33a0: 6e 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66  ns as obtained f
33b0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
33c0: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a  umn_name()]..**.
33d0: 2a 2a 20 7b 46 31 32 31 32 35 7d 20 49 66 20 74  ** {F12125} If t
33e0: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
33f0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
3400: 63 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65  c()] is NULL the
3410: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  n.**          [s
3420: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6e  qlite3_exec()] n
3430: 65 76 65 72 20 69 6e 76 6f 6b 65 73 20 61 20 63  ever invokes a c
3440: 61 6c 6c 62 61 63 6b 2e 20 20 41 6c 6c 20 71 75  allback.  All qu
3450: 65 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ery.**          
3460: 72 65 73 75 6c 74 73 20 61 72 65 20 73 69 6c 65  results are sile
3470: 6e 74 6c 79 20 64 69 73 63 61 72 64 65 64 2e 0a  ntly discarded..
3480: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 31 7d 20 49  **.** {F12131} I
3490: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
34a0: 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20  s while parsing 
34b0: 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e  or evaluating an
34c0: 79 20 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20  y of the SQL.** 
34d0: 20 20 20 20 20 20 20 20 20 68 61 6e 64 65 64 20           handed 
34e0: 69 6e 20 74 68 65 20 53 20 70 61 72 61 6d 65 74  in the S paramet
34f0: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  er of [sqlite3_e
3500: 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20  xec(D,S,C,A,E)] 
3510: 61 6e 64 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  and if.**       
3520: 20 20 20 74 68 65 20 45 20 70 61 72 61 6d 65 74     the E paramet
3530: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
3540: 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78  then [sqlite3_ex
3550: 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 74 6f 72  ec()] shall stor
3560: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
3570: 20 2a 45 20 61 6e 20 61 70 70 72 6f 70 72 69 61   *E an appropria
3580: 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
3590: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
35a0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  mory obtained.**
35b0: 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b            from [
35c0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
35d0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 34  ]..**.** {F12134
35e0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
35f0: 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20  xec(D,S,C,A,E)] 
3600: 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65  routine shall se
3610: 74 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  t the value of.*
3620: 2a 20 20 20 20 20 20 20 20 20 20 2a 45 20 74 6f  *          *E to
3630: 20 4e 55 4c 4c 20 69 66 20 45 20 69 73 20 6e 6f   NULL if E is no
3640: 74 20 4e 55 4c 4c 20 61 6e 64 20 74 68 65 72 65  t NULL and there
3650: 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a   are no errors..
3660: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 37 7d 20 54  **.** {F12137} T
3670: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
3680: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 66 75 6e  (D,S,C,A,E)] fun
3690: 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20  ction shall set 
36a0: 74 68 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  the [error code]
36b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
36c0: 20 6d 65 73 73 61 67 65 20 61 63 63 65 73 73 69   message accessi
36d0: 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ble via [sqlite3
36e0: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
36f0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3700: 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64  3_errmsg()], and
3710: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3720: 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  16()]..**.** {F1
3730: 32 31 33 38 7d 20 49 66 20 74 68 65 20 53 20 70  2138} If the S p
3740: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
3750: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c  ite3_exec(D,S,C,
3760: 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72  A,E)] is NULL or
3770: 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
3780: 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
3790: 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67  contains nothing
37a0: 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74   other than whit
37b0: 65 73 70 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73  espace, comments
37c0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  ,.**          an
37d0: 64 2f 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c  d/or semicolons,
37e0: 20 74 68 65 6e 20 72 65 73 75 6c 74 73 20 6f 66   then results of
37f0: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
3800: 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  e()],.**        
3810: 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73    [sqlite3_errms
3820: 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  g()], and [sqlit
3830: 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a  e3_errmsg16()].*
3840: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
3850: 20 72 65 73 65 74 20 74 6f 20 69 6e 64 69 63 61   reset to indica
3860: 74 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a  te no errors..**
3870: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
3880: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 31 7d 20  .**.** {U12141} 
3890: 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
38a0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
38b0: 65 78 65 63 28 29 5d 20 6d 75 73 74 20 62 65 20  exec()] must be 
38c0: 61 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65  an valid and ope
38d0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  n.**          [d
38e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38f0: 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31  on]..**.** {U121
3900: 34 32 7d 20 54 68 65 20 64 61 74 61 62 61 73 65  42} The database
3910: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
3920: 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20 77   not be closed w
3930: 68 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  hile.**         
3940: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3950: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ] is running..**
3960: 0a 2a 2a 20 7b 55 31 32 31 34 33 7d 20 54 68 65  .** {U12143} The
3970: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
3980: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71  n should use [sq
3990: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f  lite3_free()] to
39a0: 20 66 72 65 65 0a 2a 2a 20 20 20 20 20 20 20 20   free.**        
39b0: 20 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61    the memory tha
39c0: 74 20 2a 65 72 72 6d 73 67 20 69 73 20 6c 65 66  t *errmsg is lef
39d0: 74 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 6f 6e  t pointing at on
39e0: 63 65 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ce the error.** 
39f0: 20 20 20 20 20 20 20 20 20 6d 65 73 73 61 67 65           message
3a00: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
3a10: 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  eded..**.** {U12
3a20: 31 34 35 7d 20 54 68 65 20 53 51 4c 20 73 74 61  145} The SQL sta
3a30: 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 20 74  tement text in t
3a40: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
3a50: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
3a60: 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  c()].**         
3a70: 20 6d 75 73 74 20 72 65 6d 61 69 6e 20 75 6e 63   must remain unc
3a80: 68 61 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 71  hanged while [sq
3a90: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
3ab0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
3ac0: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
3ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ae0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
3af0: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
3b00: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
3b10: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
3b20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b30: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
3b40: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
3b50: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
3b60: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
3b70: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
3b80: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
3b90: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
3ba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bb0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
3bc0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
3bd0: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
3be0: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
3bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c00: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
3c10: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
3c20: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
3c30: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
3c40: 43 6f 64 65 73 20 7b 46 31 30 32 31 30 7d 0a 2a  Codes {F10210}.*
3c50: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
3c60: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
3c70: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
3c80: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
3c90: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
3ca0: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
3cb0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
3cc0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
3cd0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
3ce0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
3cf0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
3d00: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
3d10: 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72  cates success or
3d20: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
3d30: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
3d40: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
3d50: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
3d60: 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  odes].*/.#define
3d70: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
3d80: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
3d90: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
3da0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
3db0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
3dc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
3dd0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
3de0: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
3df0: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
3e00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3e10: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
3e20: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
3e30: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
3e40: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
3e50: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
3e60: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
3e70: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
3e80: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
3e90: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
3ea0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
3eb0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
3ec0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
3ed0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3ee0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
3ef0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
3f00: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
3f10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3f20: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
3f30: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
3f40: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
3f50: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
3f60: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
3f70: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
3f80: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
3f90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3fa0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
3fb0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
3fc0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
3fd0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
3fe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
3ff0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4000: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4010: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4020: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4040: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4050: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4060: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4070: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4080: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4090: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
40a0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
40b0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
40c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
40d0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
40e0: 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45   12   /* NOT USE
40f0: 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f  D. Table or reco
4100: 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a  rd not found */.
4110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4120: 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20  ULL        13   
4130: 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69  /* Insertion fai
4140: 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61  led because data
4150: 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a  base is full */.
4160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4170: 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20  ANTOPEN    14   
4180: 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65  /* Unable to ope
4190: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
41a0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
41b0: 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20  QLITE_PROTOCOL  
41c0: 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53    15   /* NOT US
41d0: 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63  ED. Database loc
41e0: 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72  k protocol error
41f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4200: 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31  TE_EMPTY       1
4210: 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
4220: 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66  is empty */.#def
4230: 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d  ine SQLITE_SCHEM
4240: 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54  A      17   /* T
4250: 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
4260: 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64  ma changed */.#d
4270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f  efine SQLITE_TOO
4280: 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a  BIG      18   /*
4290: 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   String or BLOB 
42a0: 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d  exceeds size lim
42b0: 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  it */.#define SQ
42c0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
42d0: 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64   19   /* Abort d
42e0: 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74  ue to constraint
42f0: 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64   violation */.#d
4300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4310: 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a  MATCH    20   /*
4320: 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61   Data type misma
4330: 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tch */.#define S
4340: 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20  QLITE_MISUSE    
4350: 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72    21   /* Librar
4360: 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74  y used incorrect
4370: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
4380: 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20  LITE_NOLFS      
4390: 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53   22   /* Uses OS
43a0: 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75   features not su
43b0: 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20  pported on host 
43c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
43d0: 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33  E_AUTH        23
43e0: 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74     /* Authorizat
43f0: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
4400: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52  efine SQLITE_FOR
4410: 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a  MAT      24   /*
4420: 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62   Auxiliary datab
4430: 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72  ase format error
4440: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4450: 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32  TE_RANGE       2
4460: 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d  5   /* 2nd param
4470: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
4480: 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67  bind out of rang
4490: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
44a0: 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20  ITE_NOTADB      
44b0: 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65  26   /* File ope
44c0: 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ned that is not 
44d0: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
44e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
44f0: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
4500: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
4510: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
4520: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
4530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
4540: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4550: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4560: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4570: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4580: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4590: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
45a0: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
45b0: 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 30 32 32  ult Codes {F1022
45c0: 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0}.** KEYWORDS: 
45d0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
45e0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
45f0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4600: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4610: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d  ded result code}
4620: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4630: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49  t codes}.**.** I
4640: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4650: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4660: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4670: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32   return one of 2
4680: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
4690: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
46a0: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
46b0: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
46c0: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
46d0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
46e0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
46f0: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
4700: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
4710: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
4720: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4730: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4740: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4750: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4760: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4770: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4780: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4790: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
47a0: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
47b0: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
47c0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
47d0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
47e0: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
47f0: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
4800: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
4810: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ors. The extende
4820: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
4830: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4840: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4850: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4860: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4870: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4880: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4890: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
48a0: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
48b0: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74  he available ext
48c0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
48d0: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65  es are listed he
48e0: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65  re..** One may e
48f0: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
4900: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
4910: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
4920: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
4930: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
4940: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
4950: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4960: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
4970: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
4980: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
4990: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
49a0: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
49b0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
49c0: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
49d0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
49e0: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
49f0: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
4a00: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ro..**.** INVARI
4a10: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  ANTS:.**.** {F10
4a20: 32 32 33 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69  223} The symboli
4a30: 63 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78  c name for an ex
4a40: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4a50: 64 65 20 61 6c 77 61 79 73 20 63 6f 6e 74 61 69  de always contai
4a60: 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ns.**          a
4a70: 20 72 65 6c 61 74 65 64 20 70 72 69 6d 61 72 79   related primary
4a80: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20   result code as 
4a90: 61 20 70 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20  a prefix..**.** 
4aa0: 7b 46 31 30 32 32 34 7d 20 50 72 69 6d 61 72 79  {F10224} Primary
4ab0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d   result code nam
4ac0: 65 73 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e  es contain a sin
4ad0: 67 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65  gle "_" characte
4ae0: 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 35  r..**.** {F10225
4af0: 7d 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c  } Extended resul
4b00: 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 63 6f 6e  t code names con
4b10: 74 61 69 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65  tain two or more
4b20: 20 22 5f 22 20 63 68 61 72 61 63 74 65 72 73 2e   "_" characters.
4b30: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 36 7d 20  .**.** {F10226} 
4b40: 54 68 65 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  The numeric valu
4b50: 65 20 6f 66 20 61 6e 20 65 78 74 65 6e 64 65 64  e of an extended
4b60: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 63 6f 6e   result code con
4b70: 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  tains the.**    
4b80: 20 20 20 20 20 20 6e 75 6d 65 72 69 63 20 76 61        numeric va
4b90: 6c 75 65 20 6f 66 20 69 74 73 20 63 6f 72 72 65  lue of its corre
4ba0: 73 70 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79  sponding primary
4bb0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 69 6e 0a   result code in.
4bc0: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74 73 20  **          its 
4bd0: 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
4be0: 74 20 38 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65  t 8 bits..*/.#de
4bf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c00: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4c10: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c20: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4c30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4c40: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4c50: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4c60: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4c70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4c80: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4c90: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4ca0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4cb0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4cc0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4cd0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4ce0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4cf0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4d00: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4d10: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d20: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4d30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4d40: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4d50: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4d60: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4d70: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4d80: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4d90: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4da0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4db0: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4dc0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4dd0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4de0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4df0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4e00: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4e10: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4e20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e30: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4e40: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e50: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4e60: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e70: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4e80: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e90: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4ea0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4eb0: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4ec0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4ed0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4ee0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ef0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4f00: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f10: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4f20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f30: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4f40: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4f50: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4f60: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  8))../*.** CAPI3
4f70: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
4f80: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
4f90: 6f 6e 73 20 7b 46 31 30 32 33 30 7d 0a 2a 2a 0a  ons {F10230}.**.
4fa0: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
4fb0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
4fc0: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
4fd0: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
4fe0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
4ff0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
5000: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
5010: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
5020: 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  r to the xOpen m
5030: 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20  ethod of the.** 
5040: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
5050: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
5060: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5070: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
5080: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
5090: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
50a0: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
50b0: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
50c0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
50d0: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
50e0: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
50f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
5100: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
5110: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
5120: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
5130: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
5140: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
5150: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5160: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
5170: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
5180: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5190: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
51a0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
51b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
51c0: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
51d0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
51e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
51f0: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
5200: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
5210: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5220: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
5230: 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65  00001000.#define
5240: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
5250: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
5260: 30 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65  00002000.#define
5270: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
5280: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
5290: 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00004000../*.** 
52a0: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
52b0: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
52c0: 20 7b 46 31 30 32 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F10240}.**.** 
52d0: 54 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62  The xDeviceCapab
52e0: 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f  ilities method o
52f0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
5300: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62  o_methods].** ob
5310: 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ject returns an 
5320: 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
5330: 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65   a vector of the
5340: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61   these.** bit va
5350: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20  lues expressing 
5360: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74  I/O characterist
5370: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20  ics of the mass 
5380: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63  storage.** devic
5390: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65  e that holds the
53a0: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b   file that the [
53b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
53c0: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f  ds].** refers to
53d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
53e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
53f0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5400: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
5410: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
5420: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
5430: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5440: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
5450: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
5460: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
5470: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
5480: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
5490: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
54a0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
54b0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
54c0: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
54d0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
54e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
54f0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
5500: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
5510: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
5520: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
5530: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
5540: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
5550: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
5560: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
5570: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
5580: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
5590: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
55a0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
55b0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
55c0: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
55d0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
55e0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
55f0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
5600: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
5610: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5620: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
5630: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5640: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
5650: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
5660: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5670: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5680: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
5690: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
56a0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
56b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
56c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
56d0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
56e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
56f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
5700: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5710: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
5720: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5730: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5740: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
5750: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
5760: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5770: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
5780: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
5790: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
57a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
57b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
57c0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
57d0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
57e0: 4e 44 20 20 20 20 20 30 78 30 30 30 30 30 32 30  ND     0x0000020
57f0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5800: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
5810: 4c 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30  L      0x0000040
5820: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
5830: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20  F: File Locking 
5840: 4c 65 76 65 6c 73 20 7b 46 31 30 32 35 30 7d 0a  Levels {F10250}.
5850: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5860: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5870: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5880: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5890: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
58a0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
58b0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
58c0: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
58d0: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
58e0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
58f0: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5900: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5910: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5930: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5940: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5950: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5960: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5970: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5980: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5990: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
59a0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
59b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
59c0: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
59d0: 65 20 46 6c 61 67 73 20 7b 46 31 30 32 36 30 7d  e Flags {F10260}
59e0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
59f0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
5a00: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
5a10: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
5a20: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
5a30: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
5a40: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
5a50: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
5a60: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
5a70: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
5a80: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
5a90: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
5aa0: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
5ab0: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
5ac0: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
5ad0: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
5ae0: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
5af0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
5b00: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
5b10: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
5b20: 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54  ushed. The SQLIT
5b30: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c  E_SYNC_NORMAL fl
5b40: 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  ag means.** to u
5b50: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
5b60: 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65  ) semantics. The
5b70: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
5b80: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20  L flag means.** 
5b90: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58 20  to use Mac OS-X 
5ba0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
5bb0: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
5bc0: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
5bd0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
5be0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
5bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5c00: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
5c10: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
5c20: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5c30: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
5c40: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
5c50: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
5c60: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
5c70: 6c 65 20 7b 46 31 31 31 31 30 7d 0a 2a 2a 0a 2a  le {F11110}.**.*
5c80: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
5c90: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
5ca0: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
5cb0: 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20  le in the OS.** 
5cc0: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e  interface layer.
5cd0: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
5ce0: 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d  interface implem
5cf0: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a  entations will.*
5d00: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61  * want to subcla
5d10: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62  ss this object b
5d20: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69  y appending addi
5d30: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
5d40: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75   for their own u
5d50: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64  se.  The pMethod
5d60: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69  s entry is a poi
5d70: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
5d80: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5d90: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
5da0: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66  efines methods f
5db0: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a  or performing.**
5dc0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
5dd0: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  on the open file
5de0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
5df0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
5e00: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73   sqlite3_file;.s
5e10: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
5e20: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72  le {.  const str
5e30: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
5e40: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73  ethods *pMethods
5e50: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f  ;  /* Methods fo
5e60: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a  r an open file *
5e70: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
5e80: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
5e90: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20  ce File Virtual 
5ea0: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b  Methods Object {
5eb0: 46 31 31 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 45 76  F11120}.**.** Ev
5ec0: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
5ed0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
5ee0: 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f  vfs] xOpen metho
5ef0: 64 20 63 6f 6e 74 61 69 6e 73 20 61 20 70 6f 69  d contains a poi
5f00: 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 69 6e  nter to.** an in
5f10: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
5f20: 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
5f30: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 0a  ect defines the.
5f40: 2a 2a 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  ** methods used 
5f50: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
5f60: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 67  us operations ag
5f70: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
5f80: 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ile..**.** The f
5f90: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
5fa0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
5fb0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
5fc0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
5fd0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
5fe0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
5ff0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
6000: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
6010: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
6020: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 2d 58 20  e is a Mac OS-X 
6030: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
6040: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
6050: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
6060: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
6070: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
6080: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
6090: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
60a0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
60b0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
60c0: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
60d0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
60e0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
60f0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
6100: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
6110: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6120: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
6130: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6140: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
6150: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6160: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
6170: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6180: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
6190: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
61a0: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
61b0: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
61c0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
61d0: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
61e0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
61f0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
6200: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
6210: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
6220: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
6230: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
6240: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
6250: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
6260: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
6270: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
6280: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
6290: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
62a0: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
62b0: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
62c0: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
62d0: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
62e0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
62f0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
6300: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
6310: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
6320: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
6330: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
6340: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6350: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
6360: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
6370: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
6380: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
6390: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
63a0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
63b0: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
63c0: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
63d0: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
63e0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
63f0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
6400: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
6410: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
6420: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
6430: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
6440: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
6450: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
6460: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
6470: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
6480: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
6490: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
64a0: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
64b0: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
64c0: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
64d0: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
64e0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
64f0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
6500: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
6510: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
6520: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
6530: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
6540: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
6550: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
6560: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
6570: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
6580: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
6590: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
65a0: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
65b0: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
65c0: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
65d0: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
65e0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
65f0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
6600: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
6610: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
6620: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
6630: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
6640: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
6650: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a  d conflicts..**.
6660: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
6670: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
6680: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
6690: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
66a0: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
66b0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
66c0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
66d0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
66e0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
66f0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
6700: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
6710: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
6720: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
6730: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
6740: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
6750: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
6760: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
6770: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
6780: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
6790: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
67a0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
67b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
67c0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
67d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
67e0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
67f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6800: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
6810: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6820: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
6830: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6840: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
6850: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6860: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
6870: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6880: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
6890: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
68a0: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
68b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
68c0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
68d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
68e0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
68f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6900: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
6910: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
6920: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6930: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
6940: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
6950: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
6960: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
6970: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6980: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
6990: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
69a0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
69b0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
69c0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
69d0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
69e0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
69f0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6a00: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6a10: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6a20: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6a30: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6a40: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6a50: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6a60: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6a70: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
6a80: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
6a90: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6aa0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6ab0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
6ac0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
6ad0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6ae0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6af0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6b00: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6b10: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6b20: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6b30: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6b40: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6b50: 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
6b60: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
6b70: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
6b80: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
6b90: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
6ba0: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
6bb0: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
6bc0: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
6bd0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
6be0: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
6bf0: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
6c00: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
6c10: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
6c20: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
6c30: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
6c40: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
6c50: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
6c60: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
6c70: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
6c80: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
6c90: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
6ca0: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
6cb0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
6cc0: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
6cd0: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
6ce0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
6cf0: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
6d00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
6d10: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6d20: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
6d30: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
6d40: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
6d50: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
6d60: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
6d70: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
6d80: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
6d90: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
6da0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
6db0: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
6dc0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
6dd0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
6de0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
6df0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6e00: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
6e10: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74  le*);.  /* Addit
6e20: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61  ional methods ma
6e30: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
6e40: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f  ture releases */
6e50: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
6e60: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69  REF: Standard Fi
6e70: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64  le Control Opcod
6e80: 65 73 20 7b 46 31 31 33 31 30 7d 0a 2a 2a 0a 2a  es {F11310}.**.*
6e90: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
6ea0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
6eb0: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
6ec0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
6ed0: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
6ee0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6ef0: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20   object and for 
6f00: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6f10: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20  e_control()].** 
6f20: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
6f30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
6f40: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
6f50: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
6f60: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
6f70: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
6f80: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
6f90: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
6fa0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
6fb0: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
6fc0: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
6fd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
6fe0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
6ff0: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
7000: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
7010: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
7020: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
7030: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7040: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
7050: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
7060: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
7070: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
7080: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
7090: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
70a0: 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  ing and only nee
70b0: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
70c0: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
70d0: 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65  EST.** is define
70e0: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
70f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
7100: 54 41 54 45 20 20 20 20 20 20 20 20 31 0a 0a 2f  TATE        1../
7110: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
7120: 75 74 65 78 20 48 61 6e 64 6c 65 20 7b 46 31 37  utex Handle {F17
7130: 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  110}.**.** The m
7140: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
7150: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
7160: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
7170: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
7180: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
7190: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
71a0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
71b0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
71c0: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
71d0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
71e0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
71f0: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
7200: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
7210: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
7220: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
7230: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
7240: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
7250: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
7260: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
7270: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
7280: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
7290: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
72a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
72b0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
72c0: 74 20 7b 46 31 31 31 34 30 7d 0a 2a 2a 0a 2a 2a  t {F11140}.**.**
72d0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
72e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
72f0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
7300: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
7310: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
7320: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
7330: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
7340: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
7350: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
7360: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
7370: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
7380: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
7390: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  stem"..**.** The
73a0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
73b0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
73c0: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
73d0: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
73e0: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
73f0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
7400: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
7410: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
7420: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
7430: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
7440: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
7450: 6e 63 72 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  ncreased..**.** 
7460: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
7470: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
7480: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
7490: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
74a0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
74b0: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
74c0: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
74d0: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
74e0: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
74f0: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
7500: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
7510: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
7520: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
7530: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
7540: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
7550: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
7560: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
7570: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
7580: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
7590: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
75a0: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
75b0: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
75c0: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
75d0: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
75e0: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
75f0: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
7600: 65 73 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a  es the list..**.
7610: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
7620: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
7630: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
7640: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
7650: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
7660: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
7670: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
7680: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
7690: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
76a0: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
76b0: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
76c0: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
76d0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
76e0: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
76f0: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
7700: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
7710: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
7720: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
7730: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
7740: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
7750: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
7760: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
7770: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
7780: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
7790: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
77a0: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
77b0: 2a 0a 2a 2a 20 7b 46 31 31 31 34 31 7d 20 53 51  *.** {F11141} SQ
77c0: 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e  Lite will guaran
77d0: 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69  tee that the zFi
77e0: 6c 65 6e 61 6d 65 20 73 74 72 69 6e 67 20 70 61  lename string pa
77f0: 73 73 65 64 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e  ssed to.** xOpen
7800: 28 29 20 69 73 20 61 20 66 75 6c 6c 20 70 61 74  () is a full pat
7810: 68 6e 61 6d 65 20 61 73 20 67 65 6e 65 72 61 74  hname as generat
7820: 65 64 20 62 79 20 78 46 75 6c 6c 50 61 74 68 6e  ed by xFullPathn
7830: 61 6d 65 28 29 20 61 6e 64 0a 2a 2a 20 74 68 61  ame() and.** tha
7840: 74 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  t the string wil
7850: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
7860: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
7870: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
7880: 6c 6c 65 64 2e 20 20 7b 45 4e 44 7d 20 53 6f 20  lled.  {END} So 
7890: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
78a0: 65 5d 20 63 61 6e 20 73 74 6f 72 65 20 61 20 70  e] can store a p
78b0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
78c0: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
78d0: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
78e0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
78f0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
7900: 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34 32 7d 20 54  **.** {F11142} T
7910: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
7920: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
7930: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
7940: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
7950: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
7960: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
7970: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
7980: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
7990: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
79a0: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
79b0: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
79c0: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
79d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
79e0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
79f0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45  OPEN_CREATE]. {E
7a00: 4e 44 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ND}.** If xOpen(
7a10: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
7a20: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
7a30: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
7a40: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
7a50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
7a60: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
7a70: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
7a80: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
7a90: 2a 2a 20 7b 46 31 31 31 34 33 7d 20 53 51 4c 69  ** {F11143} SQLi
7aa0: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
7ab0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
7ac0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
7ad0: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
7ae0: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
7af0: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
7b00: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
7b10: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
7b20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
7b30: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
7b40: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
7b50: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
7b60: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
7b70: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
7b80: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
7b90: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
7ba0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
7bb0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
7bc0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7bd0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
7be0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7bf0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
7c00: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20  URNAL].** </ul> 
7c10: 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  {END}.**.** The 
7c20: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
7c30: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
7c40: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
7c50: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
7c60: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
7c70: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
7c80: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
7c90: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
7ca0: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
7cb0: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
7cc0: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
7cd0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
7ce0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
7cf0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
7d00: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
7d10: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
7d20: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
7d30: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
7d40: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
7d50: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
7d60: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
7d70: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
7d80: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
7d90: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
7da0: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
7db0: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
7dc0: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
7dd0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
7de0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
7df0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
7e00: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
7e10: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
7e20: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
7e30: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
7e40: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
7e50: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
7e60: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
7e70: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
7e80: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7e90: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
7ea0: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
7eb0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
7ec0: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
7ed0: 0a 2a 2a 20 7b 46 31 31 31 34 35 7d 20 54 68 65  .** {F11145} The
7ee0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
7ef0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
7f00: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
7f10: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
7f20: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
7f30: 20 63 6c 6f 73 65 64 2e 20 20 7b 46 31 31 31 34   closed.  {F1114
7f40: 36 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  6} The [SQLITE_O
7f50: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
7f60: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
7f70: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
7f80: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
7f90: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
7fa0: 61 6c 73 2e 0a 2a 2a 20 7b 46 31 31 31 34 37 7d  als..** {F11147}
7fb0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
7fc0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
7fd0: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
7fe0: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
7ff0: 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69  d.** for exclusi
8000: 76 65 20 61 63 63 65 73 73 2e 20 20 54 68 69 73  ve access.  This
8010: 20 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f 72   flag is set for
8020: 20 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65 70   all files excep
8030: 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61 69  t.** for the mai
8040: 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
8050: 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31   {END}.**.** {F1
8060: 31 31 34 38 7d 20 41 74 20 6c 65 61 73 74 20 73  1148} At least s
8070: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
8080: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
8090: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
80a0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
80b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
80c0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
80d0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
80e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
80f0: 6e 2e 20 20 7b 45 4e 44 7d 20 20 54 68 65 20 78  n.  {END}  The x
8100: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
8110: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
8120: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
8130: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
8140: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
8150: 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34 39  n..**.** {F11149
8160: 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  } The flags argu
8170: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
8180: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
8190: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
81a0: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
81b0: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
81c0: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
81d0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
81e0: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
81f0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
8200: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
8210: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
8220: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
8230: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
8240: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
8250: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
8260: 20 20 7b 45 4e 44 7d 20 54 68 65 20 66 69 6c 65    {END} The file
8270: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
8280: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ectory..**.** {F
8290: 31 31 31 35 30 7d 20 53 51 4c 69 74 65 20 77 69  11150} SQLite wi
82a0: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
82b0: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
82c0: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
82d0: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
82e0: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
82f0: 68 6e 61 6d 65 2e 20 7b 46 31 31 31 35 31 7d 20  hname. {F11151} 
8300: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
8310: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
8320: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
8330: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
8340: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
8350: 74 68 6f 64 73 2e 20 7b 45 4e 44 7d 20 49 66 20  thods. {END} If 
8360: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
8370: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
8380: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
8390: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
83a0: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
83b0: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
83c0: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
83d0: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
83e0: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
83f0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
8400: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
8410: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
8420: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
8430: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
8440: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
8450: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
8460: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
8470: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
8480: 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65  Time() interface
8490: 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72  s.** are not str
84a0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
84b0: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
84c0: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
84d0: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
84e0: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
84f0: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
8500: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
8510: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
8520: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
8530: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
8540: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
8550: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
8560: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
8570: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
8580: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
8590: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
85a0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
85b0: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
85c0: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
85d0: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
85e0: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
85f0: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
8600: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
8610: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54  econds given.  T
8620: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
8630: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
8640: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
8650: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
8660: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
8670: 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   time..*/.typede
8680: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
8690: 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73  _vfs sqlite3_vfs
86a0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
86b0: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
86c0: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
86d0: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
86e0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f  ersion number */
86f0: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
8700: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
8710: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
8720: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
8730: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
8740: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
8750: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
8760: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
8770: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
8780: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
8790: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
87a0: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
87b0: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
87c0: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
87d0: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
87e0: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
87f0: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
8800: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
8810: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
8820: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
8830: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
8840: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
8850: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
8860: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
8870: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
8880: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
8890: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
88a0: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
88b0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
88c0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
88d0: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
88e0: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
88f0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
8900: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
8910: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
8920: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
8930: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
8940: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
8950: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
8960: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
8970: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
8980: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
8990: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
89a0: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
89b0: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
89c0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
89d0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
89e0: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28  rMsg);.  void *(
89f0: 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
8a00: 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
8a10: 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
8a20: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
8a30: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
8a40: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
8a50: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
8a60: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
8a70: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
8a80: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
8a90: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
8aa0: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
8ab0: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
8ac0: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
8ad0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
8ae0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
8af0: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
8b00: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
8b10: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65  char *);.  /* Ne
8b20: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
8b30: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
8b40: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
8b50: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
8b60: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
8b70: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
8b80: 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d  is happens. */.}
8b90: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8ba0: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
8bb0: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
8bc0: 68 6f 64 20 7b 46 31 31 31 39 30 7d 0a 2a 2a 0a  hod {F11190}.**.
8bd0: 2a 2a 20 7b 46 31 31 31 39 31 7d 20 54 68 65 73  ** {F11191} Thes
8be0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
8bf0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
8c00: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
8c10: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
8c20: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
8c30: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
8c40: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44  fs] object. {END
8c50: 7d 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  }  They determin
8c60: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
8c70: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
8c80: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
8c90: 20 69 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67 20 66   is.** looking f
8ca0: 6f 72 2e 20 20 7b 46 31 31 31 39 32 7d 20 57 69  or.  {F11192} Wi
8cb0: 74 68 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  th [SQLITE_ACCES
8cc0: 53 5f 45 58 49 53 54 53 5d 2c 20 74 68 65 20 78  S_EXISTS], the x
8cd0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
8ce0: 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 74   simply checks t
8cf0: 6f 20 73 65 65 20 69 66 20 74 68 65 20 66 69 6c  o see if the fil
8d00: 65 20 65 78 69 73 74 73 2e 20 7b 46 31 31 31 39  e exists. {F1119
8d10: 33 7d 20 57 69 74 68 0a 2a 2a 20 53 51 4c 49 54  3} With.** SQLIT
8d20: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
8d30: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
8d40: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 74 6f  method checks to
8d50: 20 73 65 65 0a 2a 2a 20 69 66 20 74 68 65 20 66   see.** if the f
8d60: 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61 64  ile is both read
8d70: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
8d80: 65 2e 20 20 7b 46 31 31 31 39 34 7d 20 57 69 74  e.  {F11194} Wit
8d90: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 41 43 43 45  h.** SQLITE_ACCE
8da0: 53 53 5f 52 45 41 44 20 74 68 65 20 78 41 63 63  SS_READ the xAcc
8db0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
8dc0: 65 63 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74  ecks to see if t
8dd0: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
8de0: 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ble..*/.#define 
8df0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
8e00: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
8e10: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
8e20: 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66  READWRITE 1.#def
8e30: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
8e40: 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f  S_READ      2../
8e50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
8e60: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
8e70: 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 46 31  Lite Library {F1
8e80: 30 31 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0130}.**.** The 
8e90: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
8ea0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
8eb0: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
8ec0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 70  SQLite library p
8ed0: 72 69 6f 72 20 74 6f 20 75 73 65 2e 20 20 54 68  rior to use.  Th
8ee0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
8ef0: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
8f00: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
8f10: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
8f20: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
8f30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8f40: 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  ize()..**.** A c
8f50: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
8f60: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
8f70: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
8f80: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
8f90: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
8fa0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
8fb0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
8fc0: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
8fd0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
8fe0: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
8ff0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
9000: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9010: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
9020: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
9030: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
9040: 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79  hutdown().  Only
9050: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
9060: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
9070: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
9080: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
9090: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
90a0: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
90b0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 20  armless no-ops. 
90c0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
90d0: 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
90e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
90f0: 74 69 6e 65 20 6d 61 79 20 62 65 20 63 61 6c 6c  tine may be call
9100: 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ed multiple time
9110: 73 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 6f 6e  s.** without con
9120: 73 65 71 75 65 6e 63 65 2e 20 20 53 65 63 6f 6e  sequence.  Secon
9130: 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
9140: 20 65 76 61 6c 75 61 74 69 6f 6e 73 20 6f 66 0a   evaluations of.
9150: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
9160: 61 6c 69 7a 65 28 29 20 61 72 65 20 6e 6f 2d 6f  alize() are no-o
9170: 70 73 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ps.  The sqlite3
9180: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
9190: 75 74 69 6e 65 0a 2a 2a 20 6f 6e 6c 79 20 77 6f  utine.** only wo
91a0: 72 6b 73 20 74 68 65 20 66 69 72 73 74 20 74 69  rks the first ti
91b0: 6d 65 20 69 74 20 69 73 20 63 61 6c 6c 65 64 20  me it is called 
91c0: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 2c 20 6f  for a process, o
91d0: 72 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 74  r the first.** t
91e0: 69 6d 65 20 69 74 20 69 73 20 63 61 6c 6c 65 64  ime it is called
91f0: 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
9200: 68 75 74 64 6f 77 6e 28 29 2e 20 20 49 6e 20 61  hutdown().  In a
9210: 6c 6c 20 6f 74 68 65 72 20 63 61 73 65 73 2c 0a  ll other cases,.
9220: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
9230: 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 20  alize() returns 
9240: 53 51 4c 49 54 45 5f 4f 4b 20 77 69 74 68 6f 75  SQLITE_OK withou
9250: 74 20 64 6f 69 6e 67 20 61 6e 79 20 72 65 61 6c  t doing any real
9260: 20 77 6f 72 6b 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f   work..**.** Amo
9270: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
9280: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9290: 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f  ize() shall invo
92a0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
92b0: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
92c0: 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75  rly, sqlite3_shu
92d0: 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c  tdown().** shall
92e0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
92f0: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
9300: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9310: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9320: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
9330: 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  OK on success..*
9340: 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65  * If for some re
9350: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
9360: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
9370: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
9380: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
9390: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
93a0: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
93b0: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
93c0: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
93d0: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
93e0: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
93f0: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
9400: 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a  SQLITE_OK..**.**
9410: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
9420: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
9430: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
9440: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
9450: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
9460: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
9470: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
9480: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
9490: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
94a0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
94b0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
94c0: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
94d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
94e0: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
94f0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9500: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
9510: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
9520: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
9530: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
9540: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
9550: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
9560: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
9570: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
9580: 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66  dy.  However, if
9590: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
95a0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
95b0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
95c0: 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  T.** compile-tim
95d0: 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
95e0: 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
95f0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
9600: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
9610: 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
9620: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
9630: 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
9640: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
9650: 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
9660: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
9670: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
9680: 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
9690: 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
96a0: 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
96b0: 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
96c0: 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
96d0: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
96e0: 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
96f0: 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
9700: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
9710: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
9720: 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
9730: 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
9740: 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
9750: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
9760: 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
9770: 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
9780: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
9790: 64 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4f 4d  d with SQLITE_OM
97a0: 49 54 5f 41 55 54 4f 49 4e 49 54 20 6d 69 67 68  IT_AUTOINIT migh
97b0: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
97c0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
97d0: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
97e0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
97f0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
9800: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
9810: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
9820: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
9830: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
9840: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
9850: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
9860: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
9870: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
9880: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
9890: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
98a0: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
98b0: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
98c0: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
98d0: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
98e0: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
98f0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
9900: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
9910: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
9920: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
9930: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
9940: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
9950: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
9960: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
9970: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
9980: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
9990: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
99a0: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
99b0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
99c0: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
99d0: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
99e0: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
99f0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
9a00: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
9a10: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
9a20: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
9a30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9a40: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
9a50: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
9a60: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
9a70: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
9a80: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
9a90: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
9aa0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9ab0: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
9ac0: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
9ad0: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
9ae0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
9af0: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
9b00: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
9b10: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
9b20: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
9b30: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
9b40: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
9b50: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
9b60: 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e  ed for unix, win
9b70: 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a  dows, or os/2..*
9b80: 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f 72  * When built for
9b90: 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
9ba0: 20 28 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49   (using the SQLI
9bb0: 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 20 63 6f  TE_OS_OTHER=1 co
9bc0: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
9bd0: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
9be0: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
9bf0: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
9c00: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
9c10: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
9c20: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
9c30: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
9c40: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
9c50: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
9c60: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
9c70: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
9c80: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
9c90: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53 51  * must return SQ
9ca0: 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65  LITE_OK on succe
9cb0: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
9cc0: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
9cd0: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
9ce0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
9cf0: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
9d00: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
9d10: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
9d20: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
9d30: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
9d40: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
9d50: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
9d60: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
9d70: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
9d80: 79 20 7b 46 31 30 31 34 35 7d 0a 2a 2a 0a 2a 2a  y {F10145}.**.**
9d90: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
9da0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
9db0: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
9dc0: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
9dd0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
9de0: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
9df0: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
9e00: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
9e10: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
9e20: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
9e30: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
9e40: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
9e50: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
9e60: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
9e70: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
9e80: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
9e90: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
9ea0: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
9eb0: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
9ec0: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
9ed0: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
9ee0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
9ef0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
9f00: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
9f10: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
9f20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
9f30: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
9f40: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
9f50: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
9f60: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
9f70: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
9f80: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
9f90: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
9fa0: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
9fb0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
9fc0: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
9fd0: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
9fe0: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
9ff0: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
a000: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a010: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
a020: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
a030: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
a040: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
a050: 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63  , that sqlite3_c
a060: 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
a070: 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
a080: 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
a090: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
a0a0: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
a0b0: 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
a0c0: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
a0d0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
a0e0: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
a0f0: 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
a100: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
a110: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
a120: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
a130: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
a140: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
a150: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
a160: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
a170: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
a180: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
a190: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
a1a0: 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  on the [SQLITE_C
a1b0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
a1c0: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  AD | configurati
a1d0: 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
a1e0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
a1f0: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
a200: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
a210: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
a220: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
a230: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
a240: 4b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74  K..** If the opt
a250: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
a260: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
a270: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
a280: 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
a290: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
a2a0: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
a2b0: 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e  ror code]..*/.in
a2c0: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
a2d0: 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
a2e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
a2f0: 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52  ory Allocation R
a300: 6f 75 74 69 6e 65 73 20 7b 46 31 30 31 35 35 7d  outines {F10155}
a310: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
a320: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
a330: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
a340: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
a350: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
a360: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
a370: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
a380: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
a390: 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
a3a0: 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
a3b0: 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
a3c0: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
a3d0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
a3e0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
a3f0: 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
a400: 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
a410: 65 33 5f 63 6f 6e 66 69 67 5d 20 77 68 65 6e 20  e3_config] when 
a420: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
a430: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
a440: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
a450: 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74  LLOC].  By creat
a460: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
a470: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
a480: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
a490: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
a4a0: 66 69 67 5d 20 64 75 72 69 6e 67 20 63 6f 6e 66  fig] during conf
a4b0: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a  iguration, an.**
a4c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
a4d0: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
a4e0: 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 20 61  rnative memory a
a4f0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
a500: 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c 69 74  tem.** for SQLit
a510: 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
a520: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
a530: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
a540: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
a550: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
a560: 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  a built-in memor
a570: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
a580: 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74 6c 79   is.** perfectly
a590: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
a5a0: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
a5b0: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
a5c0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
a5d0: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
a5e0: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
a5f0: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
a600: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
a610: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
a620: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
a630: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
a640: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
a650: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
a660: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
a670: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
a680: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
a690: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
a6a0: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
a6b0: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
a6c0: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
a6d0: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
a6e0: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
a6f0: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
a700: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
a710: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
a720: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
a730: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
a740: 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64 20 78  oc, xFree, and x
a750: 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 73 20  Realloc methods 
a760: 73 68 6f 75 6c 64 20 77 6f 72 6b 20 6c 69 6b 65  should work like
a770: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
a780: 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65  , free(), and re
a790: 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e  alloc() function
a7a0: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
a7b0: 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  ard library..**.
a7c0: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
a7d0: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
a7e0: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
a7f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
a800: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
a810: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
a820: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
a830: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
a840: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
a850: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
a860: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
a870: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
a880: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
a890: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
a8a0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
a8b0: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
a8c0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
a8d0: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
a8e0: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
a8f0: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
a900: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
a910: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
a920: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
a930: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
a940: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
a950: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
a960: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
a970: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
a980: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
a990: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
a9a0: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a   power of 2..**.
a9b0: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
a9c0: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
a9d0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
a9e0: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
a9f0: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
aa00: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
aa10: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
aa20: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
aa30: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
aa40: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
aa50: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
aa60: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
aa70: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
aa80: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
aa90: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
aaa0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
aab0: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
aac0: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
aad0: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
aae0: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
aaf0: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
ab00: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
ab10: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79  xShutdown..*/.ty
ab20: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
ab30: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
ab40: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
ab50: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
ab60: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
ab70: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
ab80: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
ab90: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
aba0: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
abb0: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
abc0: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
abd0: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
abe0: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
abf0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
ac00: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
ac10: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
ac20: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
ac30: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
ac40: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
ac50: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
ac60: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
ac70: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
ac80: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
ac90: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
aca0: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
acb0: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
acc0: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
acd0: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
ace0: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
acf0: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
ad00: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
ad10: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
ad20: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
ad30: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
ad40: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
ad50: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
ad60: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
ad70: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
ad80: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
ad90: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
ada0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
adb0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
adc0: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 46 31  tion Options {F1
add0: 30 31 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0160}.**.** Thes
ade0: 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
adf0: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
ae00: 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
ae10: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
ae20: 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
ae30: 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
ae40: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
ae50: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ae60: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
ae70: 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
ae80: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
ae90: 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
aea0: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
aeb0: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
aec0: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68  this option.  Th
aed0: 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c  is option disabl
aee0: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
aef0: 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
af00: 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
af10: 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
af20: 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
af30: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c   single thread.<
af40: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
af50: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
af60: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
af70: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
af80: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
af90: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
afa0: 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65  s option disable
afb0: 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
afc0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
afd0: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
afe0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
aff0: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
b000: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
b010: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
b020: 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
b030: 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
b040: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
b050: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
b060: 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
b070: 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
b080: 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
b090: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
b0a0: 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
b0b0: 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
b0c0: 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
b0d0: 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
b0e0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
b0f0: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
b100: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
b110: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
b120: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54   this option.  T
b130: 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
b140: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
b150: 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
b160: 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
b170: 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
b180: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
b190: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
b1a0: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
b1b0: 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
b1c0: 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
b1d0: 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
b1e0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
b1f0: 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52  th.** SQLITE_THR
b200: 45 41 44 53 41 46 45 3d 31 29 20 74 68 65 20 53  EADSAFE=1) the S
b210: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
b220: 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
b230: 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
b240: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
b250: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
b260: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
b270: 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
b280: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
b290: 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
b2a0: 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
b2b0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
b2c0: 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
b2d0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
b2e0: 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
b2f0: 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
b300: 74 69 6d 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  time.</dd>.**.**
b310: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
b320: 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
b330: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
b340: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
b350: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
b360: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
b370: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
b380: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
b390: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
b3a0: 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
b3b0: 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
b3c0: 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
b3d0: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
b3e0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
b3f0: 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
b400: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
b410: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
b420: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  on routines buil
b430: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f  t into SQLite.</
b440: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
b450: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
b460: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
b470: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
b480: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
b490: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
b4a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
b4b0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
b4c0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
b4d0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
b4e0: 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  e.  The [sqlite3
b4f0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
b500: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
b510: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
b520: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
b530: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b540: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54  n routines..** T
b550: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
b560: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
b570: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
b580: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b590: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
b5a0: 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
b5b0: 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
b5c0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
b5d0: 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
b5e0: 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
b5f0: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f  , for example.</
b600: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
b610: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
b620: 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
b630: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
b640: 6b 65 73 20 73 69 6e 67 6c 65 20 62 6f 6f 6c 65  kes single boole
b650: 61 6e 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  an argument whic
b660: 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
b670: 61 62 6c 65 73 0a 2a 2a 20 74 68 65 20 63 6f 6c  ables.** the col
b680: 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72  lection of memor
b690: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
b6a0: 74 69 73 74 69 63 73 2e 20 20 57 68 65 6e 20 64  tistics.  When d
b6b0: 69 73 61 62 6c 65 64 2c 20 74 68 65 0a 2a 2a 20  isabled, the.** 
b6c0: 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
b6d0: 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
b6e0: 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
b6f0: 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
b700: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
b710: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
b720: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
b730: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
b740: 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
b750: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
b760: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  eap_limit()].** 
b770: 20 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 6d    <li> sqlite3_m
b780: 65 6d 6f 72 79 5f 73 74 61 74 75 73 28 29 0a 2a  emory_status().*
b790: 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64  *   </ul>.** </d
b7a0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
b7b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
b7c0: 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CH</dt>.** <dd>T
b7d0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
b7e0: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
b7f0: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
b800: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
b810: 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  for.** scratch m
b820: 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72  emory.  There ar
b830: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
b840: 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  s:  A pointer to
b850: 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65   the memory, the
b860: 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
b870: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
b880: 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75  (sz), and the nu
b890: 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72 73 20  mber of buffers 
b8a0: 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  (N).  The sz.** 
b8b0: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
b8c0: 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31   a multiple of 1
b8d0: 36 2e 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  6. The first.** 
b8e0: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
b8f0: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f  point to an allo
b900: 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61  cation of at lea
b910: 73 74 20 28 73 7a 2b 34 29 2a 4e 20 62 79 74 65  st (sz+4)*N byte
b920: 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
b930: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
b940: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  no more than one
b950: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
b960: 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65  at once per thre
b970: 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75  ad, so.** N shou
b980: 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65  ld be set to the
b990: 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
b9a0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
b9b0: 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  ads.  The sz.** 
b9c0: 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
b9d0: 20 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 20   be 6 times the 
b9e0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
b9f0: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
ba00: 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74  e size..** Scrat
ba10: 63 68 20 62 75 66 66 65 72 73 20 61 72 65 20 75  ch buffers are u
ba20: 73 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  sed as part of t
ba30: 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65  he btree balance
ba40: 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a   operation.  If.
ba50: 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 6c  ** The btree bal
ba60: 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 69  ancer needs addi
ba70: 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65  tional memory be
ba80: 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
ba90: 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61  vided by.** scra
baa0: 74 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 69  tch buffers or i
bab0: 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66  f no scratch buf
bac0: 66 65 72 20 73 70 61 63 65 20 69 73 20 73 70 65  fer space is spe
bad0: 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c  cified, then SQL
bae0: 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b  ite.** goes to [
baf0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
bb00: 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  ] to obtain the 
bb10: 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e  memory it needs.
bb20: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bb30: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
bb40: 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
bb50: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
bb60: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
bb70: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
bb80: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
bb90: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
bba0: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
bbb0: 63 68 65 2e 20 20 54 68 65 72 65 20 61 72 65 20  che.  There are 
bbc0: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
bbd0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
bbe0: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  e.** memory, the
bbf0: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
bc00: 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
bc10: 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
bc20: 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
bc30: 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
bc40: 6d 75 73 74 20 62 65 20 61 20 70 6f 77 65 72 20  must be a power 
bc50: 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
bc60: 31 32 20 61 6e 64 20 33 32 37 36 38 2e 20 20 54  12 and 32768.  T
bc70: 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
bc80: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
bc90: 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
bca0: 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 28  on of at least (
bcb0: 73 7a 2b 34 29 2a 4e 20 62 79 74 65 73 20 6f 66  sz+4)*N bytes of
bcc0: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69   memory..** SQLi
bcd0: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
bce0: 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
bcf0: 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
bd00: 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
bd10: 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
bd20: 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
bd30: 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
bd40: 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
bd50: 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c  .  If additional
bd60: 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
bd70: 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
bd80: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
bd90: 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
bda0: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
bdb0: 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
bdc0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
bdd0: 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
bde0: 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
bdf0: 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ce.</dd>.**.** <
be00: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
be10: 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
be20: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70  d>This option sp
be30: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
be40: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
be50: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
be60: 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f  use.** for all o
be70: 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
be80: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
be90: 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f  needs beyond tho
bea0: 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66  se provided.** f
beb0: 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
bec0: 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
bed0: 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d [SQLITE_CONFIG
bee0: 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
bef0: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
bf00: 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69  arguments: A poi
bf10: 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
bf20: 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ry, the number o
bf30: 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
bf40: 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
bf50: 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
bf60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
bf70: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 69 73 20  .  When.** this 
bf80: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
bf90: 74 69 6f 6e 20 69 73 20 75 73 65 64 2c 20 53 51  tion is used, SQ
bfa0: 4c 69 74 65 20 6e 65 76 65 72 20 63 61 6c 6c 73  Lite never calls
bfb0: 20 74 68 65 20 73 79 73 74 65 6d 0a 2a 2a 20 6d   the system.** m
bfc0: 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
bfd0: 74 61 74 69 6f 6e 20 62 75 74 20 69 6e 73 74 65  tation but inste
bfe0: 61 64 20 75 73 65 73 20 74 68 65 20 73 75 70 70  ad uses the supp
bff0: 6c 69 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  lied memory buff
c000: 65 72 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79  er.** to satisfy
c010: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 6d 61   all [sqlite3_ma
c020: 6c 6c 6f 63 28 29 5d 20 72 65 71 75 65 73 74 73  lloc()] requests
c030: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
c040: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
c050: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
c060: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
c070: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
c080: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
c090: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
c0a0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
c0b0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
c0c0: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
c0d0: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
c0e0: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
c0f0: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
c100: 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
c110: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
c120: 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
c130: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
c140: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
c150: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
c160: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
c170: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
c180: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
c190: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
c1a0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
c1b0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
c1c0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
c1d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
c1e0: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
c1f0: 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
c200: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
c210: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
c220: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
c230: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
c240: 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
c250: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73  outines..** This
c260: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
c270: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
c280: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
c290: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
c2a0: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
c2b0: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
c2c0: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
c2d0: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
c2e0: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
c2f0: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
c300: 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  xample.</dd>.**.
c310: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
c320: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c330: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
c340: 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
c350: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
c360: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
c370: 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
c380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
c390: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
c3a0: 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
c3b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
c3c0: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
c3d0: 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
c3e0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
c3f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c400: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
c410: 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
c420: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
c430: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c440: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
c450: 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
c460: 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
c470: 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
c480: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
c490: 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
c4a0: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
c4b0: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
c4c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
c4d0: 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
c4e0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
c4f0: 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
c500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
c510: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
c520: 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
c530: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c540: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
c550: 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
c560: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
c570: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
c580: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
c590: 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
c5a0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
c5b0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a  ethods* */../*.*
c5c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
c5d0: 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
c5e0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
c5f0: 64 65 73 20 7b 46 31 32 32 30 30 7d 0a 2a 2a 0a  des {F12200}.**.
c600: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
c610: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
c620: 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
c630: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
c640: 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
c650: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
c660: 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
c670: 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ite. The extende
c680: 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
c690: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
c6a0: 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
c6b0: 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
c6c0: 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72 61  bility considera
c6d0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  tions..**.** INV
c6e0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
c6f0: 46 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65 77  F12201} Each new
c700: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c710: 63 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61 76  ction] shall hav
c720: 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  e the.**        
c730: 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75    [extended resu
c740: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
c750: 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
c760: 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  fault..**.** {F1
c770: 32 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  2202} The [sqlit
c780: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
c790: 6c 74 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20 69  lt_codes(D,F)] i
c7a0: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 65  nterface shall e
c7b0: 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20  nable.**        
c7c0: 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75    [extended resu
c7d0: 6c 74 20 63 6f 64 65 73 5d 20 66 6f 72 20 74 68  lt codes] for th
c7e0: 65 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  e  [database con
c7f0: 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20  nection] D.**   
c800: 20 20 20 20 20 20 20 69 66 20 74 68 65 20 46 20         if the F 
c810: 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 72 75  parameter is tru
c820: 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  e, or disable th
c830: 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73 65  em if F is false
c840: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
c850: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
c860: 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
c870: 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
c880: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
c890: 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20  st Insert Rowid 
c8a0: 7b 46 31 32 32 32 30 7d 0a 2a 2a 0a 2a 2a 20 45  {F12220}.**.** E
c8b0: 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20  ach entry in an 
c8c0: 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73  SQLite table has
c8d0: 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
c8e0: 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
c8f0: 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
c900: 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65 20 72  e "rowid". The r
c910: 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
c920: 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
c930: 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
c940: 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
c950: 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
c960: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
c970: 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
c980: 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
c990: 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
c9a0: 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a  red columns. If.
c9b0: 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
c9c0: 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
c9d0: 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52  e INTEGER PRIMAR
c9e0: 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74 20  Y KEY then that 
c9f0: 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
ca00: 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
ca10: 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
ca20: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
ca30: 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20 6f  urns the rowid o
ca40: 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
ca50: 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  t.** successful 
ca60: 49 4e 53 45 52 54 20 69 6e 74 6f 20 74 68 65 20  INSERT into the 
ca70: 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
ca80: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
ca90: 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  ection].** in th
caa0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
cab0: 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73  .  If no success
cac0: 66 75 6c 20 49 4e 53 45 52 54 73 0a 2a 2a 20 68  ful INSERTs.** h
cad0: 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
cae0: 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
caf0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
cb00: 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
cb10: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53  .**.** If an INS
cb20: 45 52 54 20 6f 63 63 75 72 73 20 77 69 74 68 69  ERT occurs withi
cb30: 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65  n a trigger, the
cb40: 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  n the rowid of t
cb50: 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
cb60: 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ow is returned b
cb70: 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61  y this routine a
cb80: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
cb90: 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67  igger is running
cba0: 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
cbb0: 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e  e trigger termin
cbc0: 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ates, the value 
cbd0: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
cbe0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65   routine.** reve
cbf0: 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20  rts to the last 
cc00: 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62  value inserted b
cc10: 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
cc20: 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41  r fired..**.** A
cc30: 6e 20 49 4e 53 45 52 54 20 74 68 61 74 20 66 61  n INSERT that fa
cc40: 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
cc50: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
cc60: 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
cc70: 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20  ccessful INSERT 
cc80: 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
cc90: 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
cca0: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
ccb0: 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73  * routine.  Thus
ccc0: 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
ccd0: 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
cce0: 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
ccf0: 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
cd00: 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
cd10: 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
cd20: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
cd30: 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
cd40: 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
cd50: 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
cd60: 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52    When INSERT OR
cd70: 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
cd80: 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
cd90: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
cda0: 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
cdb0: 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
cdc0: 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
cdd0: 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
cde0: 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
cdf0: 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
ce00: 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
ce10: 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
ce20: 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
ce30: 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
ce40: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
ce50: 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
ce60: 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70  .**.** For the p
ce70: 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
ce80: 72 6f 75 74 69 6e 65 2c 20 61 6e 20 49 4e 53 45  routine, an INSE
ce90: 52 54 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  RT is considered
cea0: 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
ceb0: 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
cec0: 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
ced0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
cee0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
cef0: 2a 0a 2a 2a 20 7b 46 31 32 32 32 31 7d 20 54 68  *.** {F12221} Th
cf00: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
cf10: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
cf20: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
cf30: 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 20 20   the rowid.**   
cf40: 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6d 6f         of the mo
cf50: 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73  st recent succes
cf60: 73 66 75 6c 20 49 4e 53 45 52 54 20 70 65 72 66  sful INSERT perf
cf70: 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 61 6d  ormed on the sam
cf80: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  e.**          [d
cf90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
cfa0: 6f 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e 20 74  on] and within t
cfb0: 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65  he same or highe
cfc0: 72 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 20 20  r level.**      
cfd0: 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74      trigger cont
cfe0: 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20  ext, or zero if 
cff0: 74 68 65 72 65 20 68 61 76 65 20 62 65 65 6e 20  there have been 
d000: 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 20 69 6e  no qualifying in
d010: 73 65 72 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  serts..**.** {F1
d020: 32 32 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  2223} The [sqlit
d030: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
d040: 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e  owid()] function
d050: 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
d060: 20 20 20 20 20 20 20 20 20 73 61 6d 65 20 76 61           same va
d070: 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c 65 64 20  lue when called 
d080: 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 72  from the same tr
d090: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a  igger context.**
d0a0: 20 20 20 20 20 20 20 20 20 20 69 6d 6d 65 64 69            immedi
d0b0: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 61 6e 64  ately before and
d0c0: 20 61 66 74 65 72 20 61 20 52 4f 4c 4c 42 41 43   after a ROLLBAC
d0d0: 4b 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  K..**.** LIMITAT
d0e0: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  IONS:.**.** {U12
d0f0: 32 33 32 7d 20 49 66 20 61 20 73 65 70 61 72 61  232} If a separa
d100: 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
d110: 6d 73 20 61 20 6e 65 77 20 49 4e 53 45 52 54 20  ms a new INSERT 
d120: 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  on the same.**  
d130: 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
d140: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
d150: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
d160: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
d170: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
d180: 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
d190: 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
d1a0: 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
d1b0: 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20  sert rowid,.**  
d1c0: 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
d1d0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
d1e0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
d1f0: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
d200: 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
d210: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
d220: 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
d230: 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
d240: 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20   or the new.**  
d250: 20 20 20 20 20 20 20 20 6c 61 73 74 20 69 6e 73          last ins
d260: 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71  ert rowid..*/.sq
d270: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
d280: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
d290: 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
d2a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d2b0: 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
d2c0: 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
d2d0: 69 65 64 20 7b 46 31 32 32 34 30 7d 0a 2a 2a 0a  ied {F12240}.**.
d2e0: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
d2f0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
d300: 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
d310: 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
d320: 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
d330: 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
d340: 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
d350: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
d360: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
d370: 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
d380: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
d390: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
d3a0: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
d3b0: 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  ** Only changes 
d3c0: 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c  that are directl
d3d0: 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  y specified by t
d3e0: 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  he INSERT, UPDAT
d3f0: 45 2c 0a 2a 2a 20 6f 72 20 44 45 4c 45 54 45 20  E,.** or DELETE 
d400: 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
d410: 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
d420: 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
d430: 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
d440: 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
d450: 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
d460: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
d470: 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  )] function.** t
d480: 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c  o find the total
d490: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
d4a0: 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  es including cha
d4b0: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
d4c0: 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41  riggers..**.** A
d4d0: 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
d4e0: 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
d4f0: 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
d500: 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
d510: 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
d520: 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
d530: 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
d540: 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
d550: 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
d560: 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 52 45  de effects of RE
d570: 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74  PLACE constraint
d580: 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20   resolution,.** 
d590: 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20  rollback, ABORT 
d5a0: 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f 50  processing, DROP
d5b0: 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 61 6e   TABLE, or by an
d5c0: 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
d5d0: 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
d5e0: 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
d5f0: 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20   changes..**.** 
d600: 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
d610: 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
d620: 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
d630: 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
d640: 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
d650: 69 70 74 20 6f 66 20 61 20 74 72 69 67 67 65 72  ipt of a trigger
d660: 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  .  Most SQL stat
d670: 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
d680: 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
d690: 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
d6a0: 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
d6b0: 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
d6c0: 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
d6d0: 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
d6e0: 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
d6f0: 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
d700: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
d710: 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
d720: 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
d730: 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
d740: 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
d750: 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
d760: 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
d770: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  tion..**.** Call
d780: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
d790: 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
d7a0: 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
d7b0: 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
d7c0: 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
d7d0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
d7e0: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
d7f0: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
d800: 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
d810: 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
d820: 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
d830: 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
d840: 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
d850: 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
d860: 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
d870: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
d880: 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
d890: 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
d8a0: 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
d8b0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
d8c0: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
d8d0: 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
d8e0: 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
d8f0: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
d900: 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
d910: 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
d920: 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 74 68 69  op level.  Withi
d930: 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20  n the body of a 
d940: 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20  trigger,.** the 
d950: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
d960: 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ) interface can 
d970: 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e  be called to fin
d980: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  d the number of.
d990: 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ** changes in th
d9a0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
d9b0: 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
d9c0: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
d9d0: 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
d9e0: 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   within the body
d9f0: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69   of the same tri
da00: 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  gger..** However
da10: 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74  , the number ret
da20: 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
da30: 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a  nclude changes.*
da40: 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74  * caused by subt
da50: 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68  riggers since th
da60: 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f  ose have their o
da70: 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  wn context..**.*
da80: 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
da90: 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20  nts the command 
daa0: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
dab0: 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48  le" without a WH
dac0: 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79  ERE clause.** by
dad0: 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65   dropping and re
dae0: 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62  creating the tab
daf0: 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75  le.  (This is mu
db00: 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67  ch faster than g
db10: 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20  oing.** through 
db20: 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64  and deleting ind
db30: 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73  ividual elements
db40: 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e   from the table.
db50: 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  )  Because of th
db60: 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69  is.** optimizati
db70: 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e  on, the deletion
db80: 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f  s in "DELETE FRO
db90: 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74  M table" are not
dba0: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64   row changes and
dbb0: 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  .** will not be 
dbc0: 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73  counted by the s
dbd0: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
dbe0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74   or [sqlite3_tot
dbf0: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a  al_changes()].**
dc00: 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61   functions, rega
dc10: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
dc20: 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
dc30: 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
dc40: 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20  nally.** in the 
dc50: 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61  table.  To get a
dc60: 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74  n accurate count
dc70: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
dc80: 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20  f rows deleted, 
dc90: 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46  use.** "DELETE F
dca0: 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20  ROM table WHERE 
dcb0: 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a  1" instead..**.*
dcc0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
dcd0: 0a 2a 2a 20 7b 46 31 32 32 34 31 7d 20 54 68 65  .** {F12241} The
dce0: 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
dcf0: 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  s()] function sh
dd00: 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 6e  all return the n
dd10: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20  umber of.**     
dd20: 20 20 20 20 20 72 6f 77 20 63 68 61 6e 67 65 73       row changes
dd30: 20 63 61 75 73 65 64 20 62 79 20 74 68 65 20 6d   caused by the m
dd40: 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
dd50: 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 20 20  T, UPDATE,.**   
dd60: 20 20 20 20 20 20 20 6f 72 20 44 45 4c 45 54 45         or DELETE
dd70: 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68   statement on th
dd80: 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
dd90: 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 0a 2a  connection and.*
dda0: 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 69  *          withi
ddb0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69  n the same or hi
ddc0: 67 68 65 72 20 74 72 69 67 67 65 72 20 63 6f 6e  gher trigger con
ddd0: 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66  text, or zero if
dde0: 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a 20 20   there have.**  
ddf0: 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e          not been
de00: 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e 67 20   any qualifying 
de10: 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  row changes..**.
de20: 2a 2a 20 7b 46 31 32 32 34 33 7d 20 53 74 61 74  ** {F12243} Stat
de30: 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f  ements of the fo
de40: 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  rm "DELETE FROM 
de50: 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68 20  tablename" with 
de60: 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 57  no.**          W
de70: 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c  HERE clause shal
de80: 6c 20 63 61 75 73 65 20 73 75 62 73 65 71 75 65  l cause subseque
de90: 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20  nt calls to.**  
dea0: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
deb0: 5f 63 68 61 6e 67 65 73 28 29 5d 20 74 6f 20 72  _changes()] to r
dec0: 65 74 75 72 6e 20 7a 65 72 6f 2c 20 72 65 67 61  eturn zero, rega
ded0: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 0a 2a 2a  rdless of the.**
dee0: 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
def0: 20 6f 66 20 72 6f 77 73 20 6f 72 69 67 69 6e 61   of rows origina
df00: 6c 6c 79 20 69 6e 20 74 68 65 20 74 61 62 6c 65  lly in the table
df10: 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49  ..**.** LIMITATI
df20: 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32  ONS:.**.** {U122
df30: 35 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  52} If a separat
df40: 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
df50: 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
df60: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
df70: 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
df80: 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65     while [sqlite
df90: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
dfa0: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
dfb0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
dfc0: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75  **          is u
dfd0: 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
dfe0: 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
dff0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
e000: 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
e010: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
e020: 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
e030: 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
e040: 64 20 7b 46 31 32 32 36 30 7d 0a 2a 2a 0a 2a 2a  d {F12260}.**.**
e050: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
e060: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
e070: 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
e080: 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52   caused by INSER
e090: 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72 20  T,.** UPDATE or 
e0a0: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
e0b0: 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74  s since the [dat
e0c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e0d0: 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  ] was opened..**
e0e0: 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75   The count inclu
e0f0: 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20  des all changes 
e100: 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72  from all trigger
e110: 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65   contexts.  Howe
e120: 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
e130: 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
e140: 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
e150: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50  to implement REP
e160: 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73  LACE constraints
e170: 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  ,.** do rollback
e180: 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
e190: 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74  ssing, or DROP t
e1a0: 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e  able processing.
e1b0: 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20  .** The changes 
e1c0: 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73  are counted as s
e1d0: 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 65  oon as the state
e1e0: 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
e1f0: 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c  them is.** compl
e200: 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73  eted (when the s
e210: 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
e220: 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
e230: 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
e240: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
e250: 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
e260: 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
e270: 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20  nts the command 
e280: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
e290: 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48  le" without a WH
e2a0: 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79  ERE clause.** by
e2b0: 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65   dropping and re
e2c0: 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62  creating the tab
e2d0: 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75  le.  (This is mu
e2e0: 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67  ch faster than g
e2f0: 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20  oing.** through 
e300: 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64  and deleting ind
e310: 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73  ividual elements
e320: 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e   from the table.
e330: 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  )  Because of th
e340: 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69  is.** optimizati
e350: 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e  on, the deletion
e360: 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f  s in "DELETE FRO
e370: 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74  M table" are not
e380: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64   row changes and
e390: 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  .** will not be 
e3a0: 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73  counted by the s
e3b0: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
e3c0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74   or [sqlite3_tot
e3d0: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a  al_changes()].**
e3e0: 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61   functions, rega
e3f0: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
e400: 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
e410: 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
e420: 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20  nally.** in the 
e430: 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61  table.  To get a
e440: 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74  n accurate count
e450: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
e460: 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20  f rows deleted, 
e470: 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46  use.** "DELETE F
e480: 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20  ROM table WHERE 
e490: 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a  1" instead..**.*
e4a0: 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
e4b0: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
e4c0: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
e4d0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
e4e0: 2a 2a 0a 2a 2a 20 7b 46 31 32 32 36 31 7d 20 54  **.** {F12261} T
e4f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
e500: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65 74  l_changes()] ret
e510: 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e  urns the total n
e520: 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  umber.**        
e530: 20 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73    of row changes
e540: 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52   caused by INSER
e550: 54 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f  T, UPDATE, and/o
e560: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20  r DELETE.**     
e570: 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20       statements 
e580: 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
e590: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e5a0: 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20  ], in any.**    
e5b0: 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f        trigger co
e5c0: 6e 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68 65  ntext, since the
e5d0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
e5e0: 74 69 6f 6e 20 77 61 73 20 63 72 65 61 74 65 64  tion was created
e5f0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 36 33 7d  ..**.** {F12263}
e600: 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74   Statements of t
e610: 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20  he form "DELETE 
e620: 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20  FROM tablename" 
e630: 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20  with no.**      
e640: 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65      WHERE clause
e650: 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e 67   shall not chang
e660: 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
e670: 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rned.**         
e680: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74   by [sqlite3_tot
e690: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 2e 0a 2a  al_changes()]..*
e6a0: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
e6b0: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 36 34 7d  :.**.** {U12264}
e6c0: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
e6d0: 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
e6e0: 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
e6f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e700: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
e710: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
e720: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
e730: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
e740: 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  the value.**    
e750: 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 69        returned i
e760: 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
e770: 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
e780: 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
e790: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
e7a0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
e7b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
e7c0: 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
e7d0: 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 46 31 32  nning Query {F12
e7e0: 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  270}.**.** This 
e7f0: 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
e800: 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
e810: 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
e820: 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
e830: 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
e840: 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
e850: 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
e860: 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
e870: 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
e880: 73 65 20 74 6f 20 61 6e 20 75 73 65 72 20 61 63  se to an user ac
e890: 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
e8a0: 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
e8b0: 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
e8c0: 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
e8d0: 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
e8e0: 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
e8f0: 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
e900: 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65  **.** It is safe
e910: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
e920: 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
e930: 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
e940: 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
e950: 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
e960: 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
e970: 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
e980: 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
e990: 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
e9a0: 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
e9b0: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
e9c0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
e9d0: 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
e9e0: 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
e9f0: 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
ea00: 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
ea10: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c  .**.** If an SQL
ea20: 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
ea30: 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
ea40: 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
ea50: 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
ea60: 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
ea70: 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
ea80: 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
ea90: 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
eaa0: 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
eab0: 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
eac0: 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
ead0: 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20  n..**.** An SQL 
eae0: 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
eaf0: 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
eb00: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
eb10: 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
eb20: 20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70   If the interrup
eb30: 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
eb40: 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
eb50: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
eb60: 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
eb70: 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
eb80: 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
eb90: 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
eba0: 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
ebb0: 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
ebc0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
ebd0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
ebe0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
ebf0: 28 29 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  () has no effect
ec00: 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
ec10: 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
ec20: 74 61 72 74 65 64 20 61 66 74 65 72 20 73 71 6c  tarted after sql
ec30: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
ec40: 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
ec50: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
ec60: 2a 20 7b 46 31 32 32 37 31 7d 20 54 68 65 20 5b  * {F12271} The [
ec70: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
ec80: 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  t()] interface w
ec90: 69 6c 6c 20 66 6f 72 63 65 20 61 6c 6c 20 72 75  ill force all ru
eca0: 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  nning.**        
ecb0: 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73    SQL statements
ecc0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
ecd0: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
ece0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
ecf0: 20 20 20 20 20 20 20 20 20 20 74 6f 20 68 61 6c            to hal
ed00: 74 20 61 66 74 65 72 20 70 72 6f 63 65 73 73 69  t after processi
ed10: 6e 67 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61  ng at most one a
ed20: 64 64 69 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66  dditional row of
ed30: 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   data..**.** {F1
ed40: 32 32 37 32 7d 20 41 6e 79 20 53 51 4c 20 73 74  2272} Any SQL st
ed50: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20  atement that is 
ed60: 69 6e 74 65 72 72 75 70 74 65 64 20 62 79 20 5b  interrupted by [
ed70: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
ed80: 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  t()].**         
ed90: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
eda0: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
edb0: 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f  .**.** LIMITATIO
edc0: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 37  NS:.**.** {U1227
edd0: 39 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61  9} If the databa
ede0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
edf0: 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
ee00: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
ee10: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
ee20: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
ee30: 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
ee40: 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
ee50: 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
ee60: 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
ee70: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ee80: 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
ee90: 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
eea0: 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 46 31 30  Is Complete {F10
eeb0: 35 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  510}.**.** These
eec0: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
eed0: 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64  eful for command
eee0: 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
eef0: 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
ef00: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
ef10: 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
ef20: 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65  to form complete
ef30: 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74   a SQL statement
ef40: 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
ef50: 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
ef60: 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
ef70: 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
ef80: 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
ef90: 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20  parsing.  These 
efa0: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
efb0: 74 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75  true if the inpu
efc0: 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
efd0: 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
efe0: 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
eff0: 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74  nt.  A statement
f000: 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
f010: 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
f020: 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
f030: 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
f040: 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67  nd is not a frag
f050: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45  ment of a.** CRE
f060: 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
f070: 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f  ement.  Semicolo
f080: 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
f090: 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
f0a0: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
f0b0: 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
f0c0: 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
f0d0: 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
f0e0: 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
f0f0: 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
f100: 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
f110: 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
f120: 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
f130: 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
f140: 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
f150: 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ent terminator..
f160: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
f170: 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
f180: 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
f190: 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
f1a0: 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
f1b0: 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
f1c0: 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
f1d0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
f1e0: 2a 20 7b 46 31 30 35 31 31 7d 20 54 68 65 20 73  * {F10511} The s
f1f0: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
f200: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
f210: 6d 70 6c 65 74 65 31 36 28 29 20 66 75 6e 63 74  mplete16() funct
f220: 69 6f 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ions.**         
f230: 20 72 65 74 75 72 6e 20 74 72 75 65 20 28 6e 6f   return true (no
f240: 6e 2d 7a 65 72 6f 29 20 69 66 20 61 6e 64 20 6f  n-zero) if and o
f250: 6e 6c 79 20 69 66 20 74 68 65 20 6c 61 73 74 20  nly if the last 
f260: 6e 6f 6e 2d 77 68 69 74 65 73 70 61 63 65 0a 2a  non-whitespace.*
f270: 2a 20 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e  *          token
f280: 20 69 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20   in their input 
f290: 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  is a semicolon t
f2a0: 68 61 74 20 69 73 20 6e 6f 74 20 69 6e 20 62 65  hat is not in be
f2b0: 74 77 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20  tween.**        
f2c0: 20 20 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20    the BEGIN and 
f2d0: 45 4e 44 20 6f 66 20 61 20 43 52 45 41 54 45 20  END of a CREATE 
f2e0: 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
f2f0: 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  t..**.** LIMITAT
f300: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 30  IONS:.**.** {U10
f310: 35 31 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74  512} The input t
f320: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  o sqlite3_comple
f330: 74 65 28 29 20 6d 75 73 74 20 62 65 20 61 20 7a  te() must be a z
f340: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
f350: 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38  *          UTF-8
f360: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
f370: 55 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75  U10513} The inpu
f380: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  t to sqlite3_com
f390: 70 6c 65 74 65 31 36 28 29 20 6d 75 73 74 20 62  plete16() must b
f3a0: 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
f3b0: 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
f3c0: 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
f3d0: 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
f3e0: 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
f3f0: 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
f400: 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
f410: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
f420: 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
f430: 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
f440: 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
f450: 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
f460: 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
f470: 59 20 45 72 72 6f 72 73 20 7b 46 31 32 33 31 30  Y Errors {F12310
f480: 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
f490: 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
f4a0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
f4b0: 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
f4c0: 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
f4d0: 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
f4e0: 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
f4f0: 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
f500: 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
f510: 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
f520: 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
f530: 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
f540: 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
f550: 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
f560: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
f570: 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
f580: 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
f590: 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
f5a0: 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
f5b0: 2e 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61  . If the busy ca
f5c0: 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
f5d0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
f5e0: 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65  callback will be
f5f0: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
f600: 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
f610: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
f620: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e  ument to the han
f630: 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
f640: 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
f650: 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
f660: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
f670: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
f680: 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 54  sy_handler().  T
f690: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
f6a0: 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e  nt to.** the han
f6b0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
f6c0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
f6d0: 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
f6e0: 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
f6f0: 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
f700: 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
f710: 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a  event.  If the.*
f720: 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
f730: 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
f740: 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
f750: 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
f760: 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
f770: 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
f780: 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
f790: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
f7a0: 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
f7b0: 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
f7c0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
f7d0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
f7e0: 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
f7f0: 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
f800: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
f810: 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
f820: 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
f830: 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
f840: 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
f850: 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
f860: 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
f870: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
f880: 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
f890: 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
f8a0: 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65  . If SQLite dete
f8b0: 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
f8c0: 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
f8d0: 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
f8e0: 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
f8f0: 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
f900: 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
f910: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
f920: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
f930: 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
f940: 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
f950: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
f960: 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
f970: 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
f980: 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
f990: 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
f9a0: 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
f9b0: 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
f9c0: 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
f9d0: 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
f9e0: 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
f9f0: 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
fa00: 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
fa10: 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
fa20: 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
fa30: 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
fa40: 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
fa50: 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
fa60: 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
fa70: 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
fa80: 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
fa90: 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
faa0: 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
fab0: 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
fac0: 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
fad0: 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
fae0: 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
faf0: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
fb00: 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
fb10: 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
fb20: 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
fb30: 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
fb40: 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
fb50: 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
fb60: 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
fb70: 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
fb80: 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
fb90: 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
fba0: 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
fbb0: 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
fbc0: 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
fbd0: 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
fbe0: 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
fbf0: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
fc00: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
fc10: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
fc20: 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
fc30: 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
fc40: 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77  RR_BLOCKED].** w
fc50: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
fc60: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
fc70: 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
fc80: 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
fc90: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
fca0: 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
fcb0: 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
fcc0: 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
fcd0: 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
fce0: 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
fcf0: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
fd00: 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
fd10: 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
fd20: 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
fd30: 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
fd40: 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
fd50: 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
fd60: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
fd70: 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
fd80: 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
fd90: 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69 74   readers.  If it
fda0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72   is unable to pr
fdb0: 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20  omote the lock, 
fdc0: 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  then the in-memo
fdd0: 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c  ry.** cache will
fde0: 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69   be left in an i
fdf0: 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74  nconsistent stat
fe00: 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72  e and so the err
fe10: 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72  or.** code is pr
fe20: 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20  omoted from the 
fe30: 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67  relatively benig
fe40: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
fe50: 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  to.** the more s
fe60: 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f  evere [SQLITE_IO
fe70: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54  ERR_BLOCKED].  T
fe80: 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
fe90: 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
fea0: 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
feb0: 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
fec0: 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68  changes.  See th
fed0: 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63  e.** <a href="/c
fee0: 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f  vstrac/wiki?p=Co
fef0: 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
ff00: 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20  gBusyError">.** 
ff10: 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
ff20: 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e  ingBusyError</a>
ff30: 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61   wiki page for a
ff40: 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77   discussion of w
ff50: 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d  hy.** this is im
ff60: 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  portant..**.** T
ff70: 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
ff80: 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
ff90: 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
ffa0: 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
ffb0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
ffc0: 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
ffd0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
ffe0: 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
fff0: 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
10000 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 63  er.  Note that c
10010 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
10020 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
10030 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74  ** will also set
10040 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75   or clear the bu
10050 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
10060 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
10070 0a 2a 2a 20 7b 46 31 32 33 31 31 7d 20 54 68 65  .** {F12311} The
10080 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
10090 61 6e 64 6c 65 72 28 29 5d 20 66 75 6e 63 74 69  andler()] functi
100a0 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20  on replaces the 
100b0 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
100c0 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
100d0 6b 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  k in the databas
100e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65  e connection ide
100f0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 31  ntified by the 1
10100 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  st.**          p
10110 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 61 20  arameter with a 
10120 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
10130 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
10140 68 65 20 32 6e 64 20 61 6e 64 20 33 72 64 0a 2a  he 2nd and 3rd.*
10150 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
10160 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  eters..**.** {F1
10170 32 33 31 32 7d 20 54 68 65 20 64 65 66 61 75 6c  2312} The defaul
10180 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  t busy handler f
10190 6f 72 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  or new database 
101a0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 69 73 20 4e  connections is N
101b0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  ULL..**.** {F123
101c0 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20  14} When two or 
101d0 6d 6f 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  more database co
101e0 6e 6e 65 63 74 69 6f 6e 20 73 68 61 72 65 20 61  nnection share a
101f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
10200 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
10210 72 65 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d  red_cache | comm
10220 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20  on cache],.**   
10230 20 20 20 20 20 20 20 74 68 65 20 62 75 73 79 20         the busy 
10240 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20  handler for the 
10250 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10260 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 75 73  ion currently us
10270 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
10280 74 68 65 20 63 61 63 68 65 20 69 73 20 69 6e 76  the cache is inv
10290 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 63 61  oked when the ca
102a0 63 68 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  che encounters a
102b0 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   lock..**.** {F1
102c0 32 33 31 36 7d 20 49 66 20 61 20 62 75 73 79 20  2316} If a busy 
102d0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
102e0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
102f0 68 65 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69  hen the SQLite i
10300 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20  nterface.**     
10310 20 20 20 20 20 74 68 61 74 20 70 72 6f 76 6f 6b       that provok
10320 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e 67 20 65  ed the locking e
10330 76 65 6e 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  vent will return
10340 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
10350 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 38 7d 20 53  **.** {F12318} S
10360 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
10370 65 73 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  es the busy hand
10380 6c 65 72 20 77 69 74 68 20 74 77 6f 20 61 72 67  ler with two arg
10390 75 6d 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20  uments which.** 
103a0 20 20 20 20 20 20 20 20 20 61 72 65 20 61 20 63           are a c
103b0 6f 70 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74  opy of the point
103c0 65 72 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  er supplied by t
103d0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
103e0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
103f0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
10400 6e 64 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63  ndler()] and a c
10410 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62  ount of the numb
10420 65 72 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20  er of prior.**  
10430 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69          invocati
10440 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 73 79 20  ons of the busy 
10450 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20  handler for the 
10460 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65  same locking eve
10470 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  nt..**.** LIMITA
10480 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
10490 32 33 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e  2319} A busy han
104a0 64 6c 65 72 20 73 68 6f 75 6c 64 20 6e 6f 74 20  dler should not 
104b0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
104c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
104d0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 70 72            or [pr
104e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
104f0 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
10500 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
10510 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10520 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
10530 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
10540 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
10550 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10560 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
10570 6d 65 6f 75 74 20 7b 46 31 32 33 34 30 7d 0a 2a  meout {F12340}.*
10580 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
10590 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
105a0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
105b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
105c0 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
105d0 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
105e0 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
105f0 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
10600 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65  ked.  The handle
10610 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
10620 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
10630 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
10640 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
10650 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
10660 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
10670 20 7b 46 31 32 33 34 33 7d 20 41 66 74 65 72 20   {F12343} After 
10680 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
10690 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
106a0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
106b0 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
106c0 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
106d0 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
106e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
106f0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
10700 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a  R_BLOCKED]..**.*
10710 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  * Calling this r
10720 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
10730 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
10740 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
10750 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
10760 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
10770 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63  s..**.** There c
10780 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
10790 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
107a0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
107b0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
107c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
107d0 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
107e0 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
107f0 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
10800 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
10810 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
10820 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
10830 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
10840 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
10850 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
10860 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
10870 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
10880 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 31  S:.**.** {F12341
10890 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
108a0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66  usy_timeout()] f
108b0 75 6e 63 74 69 6f 6e 20 6f 76 65 72 72 69 64 65  unction override
108c0 73 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20 20  s any prior.**  
108d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
108e0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
108f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75 73   or [sqlite3_bus
10900 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65 74  y_handler()] set
10910 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ting.**         
10920 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
10930 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10940 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 33 7d  ..**.** {F12343}
10950 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   If the 2nd para
10960 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
10970 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
10980 5d 20 69 73 20 6c 65 73 73 20 74 68 61 6e 0a 2a  ] is less than.*
10990 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 65 71  *          or eq
109a0 75 61 6c 20 74 6f 20 7a 65 72 6f 2c 20 74 68 65  ual to zero, the
109b0 6e 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  n the busy handl
109c0 65 72 20 69 73 20 63 6c 65 61 72 65 64 20 73 6f  er is cleared so
109d0 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
109e0 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74    all subsequent
109f0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20   locking events 
10a00 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75  immediately retu
10a10 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
10a20 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 34 7d  ..**.** {F12344}
10a30 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   If the 2nd para
10a40 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
10a50 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
10a60 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a  ] is a positive.
10a70 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
10a80 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73  er N, then a bus
10a90 79 20 68 61 6e 64 6c 65 72 20 69 73 20 73 65 74  y handler is set
10aa0 20 74 68 61 74 20 72 65 70 65 61 74 65 64 6c 79   that repeatedly
10ab0 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20   calls.**       
10ac0 20 20 20 74 68 65 20 78 53 6c 65 65 70 28 29 20     the xSleep() 
10ad0 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20 56 46  method in the VF
10ae0 53 20 69 6e 74 65 72 66 61 63 65 20 75 6e 74 69  S interface unti
10af0 6c 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20  l either the.** 
10b00 20 20 20 20 20 20 20 20 20 6c 6f 63 6b 20 63 6c           lock cl
10b10 65 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68  ears or until th
10b20 65 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65  e cumulative sle
10b30 65 70 20 74 69 6d 65 20 72 65 70 6f 72 74 65 64  ep time reported
10b40 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20   back.**        
10b50 20 20 62 79 20 78 53 6c 65 65 70 28 29 20 65 78    by xSleep() ex
10b60 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63  ceeds N millisec
10b70 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  onds..*/.int sql
10b80 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
10b90 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
10ba0 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
10bb0 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
10bc0 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
10bd0 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b  unning Queries {
10be0 46 31 32 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 44 65  F12370}.**.** De
10bf0 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
10c00 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
10c10 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
10c20 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
10c30 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
10c40 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
10c50 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
10c60 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
10c70 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
10c80 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
10c90 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
10ca0 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
10cb0 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
10cc0 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
10cd0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
10ce0 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
10cf0 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
10d00 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
10d10 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
10d20 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
10d30 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
10d40 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
10d50 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
10d60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
10d70 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
10d80 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
10d90 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
10da0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
10db0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
10dc0 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
10dd0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
10de0 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
10df0 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
10e00 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
10e10 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
10e20 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
10e30 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
10e40 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
10e50 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
10e60 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
10e70 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
10e80 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
10e90 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
10ea0 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
10eb0 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
10ec0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
10ed0 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
10ee0 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
10ef0 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
10f00 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
10f10 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
10f20 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
10f30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
10f40 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
10f50 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
10f60 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
10f70 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
10f80 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
10f90 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
10fa0 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
10fb0 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
10fc0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
10fd0 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
10fe0 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
10ff0 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
11000 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
11010 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  able()]..**.** A
11020 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
11030 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
11040 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
11050 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
11060 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
11070 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
11080 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
11090 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
110a0 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
110b0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
110c0 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
110d0 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
110e0 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
110f0 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
11100 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
11110 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
11120 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
11130 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
11140 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
11150 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
11160 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
11170 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
11180 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
11190 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
111a0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
111b0 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
111c0 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
111d0 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
111e0 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
111f0 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
11200 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
11210 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
11220 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
11230 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
11240 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
11250 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
11260 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
11270 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
11280 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
11290 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
112a0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
112b0 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
112c0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
112d0 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
112e0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
112f0 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
11300 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
11310 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
11320 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
11330 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
11340 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
11350 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
11360 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
11370 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
11380 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
11390 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
113a0 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
113b0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
113c0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
113d0 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  s 2nd parameter.
113e0 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 72    It returns a r
113f0 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
11400 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
11410 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
11420 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
11430 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e  After the callin
11440 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66  g function has f
11450 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
11460 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f  e result, it sho
11470 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20  uld.** pass the 
11480 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72  pointer to the r
11490 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73  esult table to s
114a0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
114b0 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
114c0 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
114d0 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
114e0 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
114f0 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
11500 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
11510 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
11520 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
11530 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
11540 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
11550 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
11560 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
11570 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
11580 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
11590 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
115a0 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
115b0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
115c0 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
115d0 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
115e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
115f0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
11600 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
11610 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
11620 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
11630 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
11640 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
11650 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
11660 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
11670 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
11680 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
11690 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
116a0 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
116b0 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
116c0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
116d0 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
116e0 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
116f0 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
11700 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
11710 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
11720 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
11730 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
11740 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
11750 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
11760 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
11770 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c  rcode()] or [sql
11780 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
11790 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
117a0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 31 7d  :.**.** {F12371}
117b0 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 67   If a [sqlite3_g
117c0 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69 6c  et_table()] fail
117d0 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
117e0 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20  ation, then.**  
117f0 20 20 20 20 20 20 20 20 69 74 20 66 72 65 65 73          it frees
11800 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
11810 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72 75 63  e under construc
11820 74 69 6f 6e 2c 20 61 62 6f 72 74 73 20 74 68 65  tion, aborts the
11830 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71 75 65  .**          que
11840 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c 20 73  ry in process, s
11850 6b 69 70 73 20 61 6e 79 20 73 75 62 73 65 71 75  kips any subsequ
11860 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73 65 74  ent queries, set
11870 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
11880 20 20 2a 72 65 73 75 6c 74 70 20 6f 75 74 70 75    *resultp outpu
11890 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c  t pointer to NUL
118a0 4c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 5b 53  L and returns [S
118b0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
118c0 0a 2a 2a 20 7b 46 31 32 33 37 33 7d 20 49 66 20  .** {F12373} If 
118d0 74 68 65 20 6e 63 6f 6c 75 6d 6e 20 70 61 72 61  the ncolumn para
118e0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
118f0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
11900 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20  s not NULL.**   
11910 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
11920 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
11930 5d 20 77 72 69 74 65 73 20 74 68 65 20 6e 75 6d  ] writes the num
11940 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
11950 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
11960 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20    result set of 
11970 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a  the query into *
11980 6e 63 6f 6c 75 6d 6e 20 69 66 20 74 68 65 20 71  ncolumn if the q
11990 75 65 72 79 20 69 73 0a 2a 2a 20 20 20 20 20 20  uery is.**      
119a0 20 20 20 20 73 75 63 63 65 73 73 66 75 6c 20 28      successful (
119b0 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  if the function 
119c0 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
119d0 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37  K)..**.** {F1237
119e0 34 7d 20 49 66 20 74 68 65 20 6e 72 6f 77 20 70  4} If the nrow p
119f0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
11a00 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
11a10 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a  ] is not NULL.**
11a20 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
11a30 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
11a40 65 28 29 5d 20 77 72 69 74 65 73 20 74 68 65 20  e()] writes the 
11a50 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69  number of rows i
11a60 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
11a70 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20    result set of 
11a80 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a  the query into *
11a90 6e 72 6f 77 20 69 66 20 74 68 65 20 71 75 65 72  nrow if the quer
11aa0 79 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  y is.**         
11ab0 20 73 75 63 63 65 73 73 66 75 6c 20 28 69 66 20   successful (if 
11ac0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
11ad0 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e  urns SQLITE_OK).
11ae0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 36 7d 20  .**.** {F12376} 
11af0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  The [sqlite3_get
11b00 5f 74 61 62 6c 65 28 29 5d 20 66 75 6e 63 74 69  _table()] functi
11b10 6f 6e 20 73 65 74 73 20 69 74 73 20 2a 6e 63 6f  on sets its *nco
11b20 6c 75 6d 6e 20 76 61 6c 75 65 20 74 6f 20 74 68  lumn value to th
11b30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
11b40 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
11b50 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
11b60 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69  t of the query i
11b70 6e 20 74 68 65 20 73 71 6c 0a 2a 2a 20 20 20 20  n the sql.**    
11b80 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c        parameter,
11b90 20 6f 72 20 74 6f 20 7a 65 72 6f 20 69 66 20 74   or to zero if t
11ba0 68 65 20 71 75 65 72 79 20 69 6e 20 73 71 6c 20  he query in sql 
11bb0 68 61 73 20 61 6e 20 65 6d 70 74 79 20 72 65 73  has an empty res
11bc0 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20  ult set..*/.int 
11bd0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
11be0 65 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  e(.  sqlite3*,  
11bf0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e             /* An
11c00 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
11c10 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
11c20 73 71 6c 2c 20 20 20 20 20 20 2f 2a 20 53 51 4c  sql,      /* SQL
11c30 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
11c40 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 52   */.  char ***pR
11c50 65 73 75 6c 74 2c 20 20 20 20 20 20 2f 2a 20 52  esult,      /* R
11c60 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
11c70 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 72  ery */.  int *nr
11c80 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  ow,            /
11c90 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
11ca0 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
11cb0 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e  here */.  int *n
11cc0 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 20  column,         
11cd0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
11ce0 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
11cf0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
11d00 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
11d10 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
11d20 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
11d30 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
11d40 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
11d50 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
11d60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
11d70 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
11d80 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
11d90 20 7b 46 31 37 34 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F17400}.**.** 
11da0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
11db0 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66  re workalikes of
11dc0 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
11dd0 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
11de0 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
11df0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
11e00 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ry..**.** The sq
11e10 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
11e20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
11e30 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
11e40 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
11e50 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
11e60 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
11e70 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11e80 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
11e90 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
11ea0 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
11eb0 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
11ec0 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
11ed0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 20  ite3_free()].   
11ee0 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
11ef0 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
11f00 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
11f10 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
11f20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
11f30 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
11f40 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
11f50 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
11f60 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74  ..**.** In sqlit
11f70 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
11f80 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
11f90 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
11fa0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
11fb0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
11fc0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
11fd0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
11fe0 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
11ff0 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
12000 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
12010 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
12020 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
12030 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
12040 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
12050 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
12060 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
12070 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
12080 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73  nprintf().  This
12090 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
120a0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
120b0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
120c0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
120d0 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
120e0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
120f0 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20   Note also that 
12100 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
12110 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
12120 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
12130 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
12140 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
12150 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
12160 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
12170 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20  to the buffer.  
12180 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
12190 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
121a0 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
121b0 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
121c0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
121d0 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
121e0 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
121f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12200 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
12210 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
12220 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
12230 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
12240 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74  .** As long as t
12250 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
12260 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
12270 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
12280 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
12290 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
122a0 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
122b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
122c0 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70    The first.** p
122d0 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
122e0 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
122f0 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
12300 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
12310 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
12320 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
12330 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
12340 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
12350 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
12360 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
12370 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
12380 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
12390 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
123a0 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
123b0 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
123c0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
123d0 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
123e0 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
123f0 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
12400 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
12410 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
12420 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
12430 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
12440 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
12450 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
12460 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ptions..**.** Th
12470 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
12480 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
12490 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
124a0 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74   a null-terminat
124b0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
124c0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
124d0 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
124e0 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
124f0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
12500 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
12510 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
12520 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
12530 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  l.  By doubling 
12540 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
12550 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
12560 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
12570 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
12580 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
12590 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
125a0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
125b0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
125c0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
125d0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
125e0 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
125f0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
12600 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
12610 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
12620 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
12630 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
12640 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
12650 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
12660 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
12670 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
12680 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
12690 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
126a0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
126b0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
126c0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
126d0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
126e0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
126f0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
12700 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
12710 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
12720 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
12730 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
12740 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
12750 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
12760 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
12770 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
12780 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
12790 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
127a0 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
127b0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
127c0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
127d0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
127e0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
127f0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
12800 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
12810 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
12820 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
12830 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
12840 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
12850 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
12860 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
12870 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
12880 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
12890 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
128a0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
128b0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
128c0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
128d0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
128e0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
128f0 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
12900 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
12910 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
12920 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
12930 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
12940 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
12950 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
12960 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
12970 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
12980 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  * The %Q option 
12990 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
129a0 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
129b0 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
129c0 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
129d0 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
129e0 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
129f0 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
12a00 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
12a10 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
12a20 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
12a30 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
12a40 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
12a50 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
12a60 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 20   single quotes) 
12a70 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
12a80 25 51 20 6f 70 74 69 6f 6e 2e 20 7b 45 4e 44 7d  %Q option. {END}
12a90 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
12aa0 65 2c 0a 2a 2a 20 6f 6e 65 20 63 6f 75 6c 64 20  e,.** one could 
12ab0 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
12ac0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
12ad0 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
12ae0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
12af0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
12b00 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
12b10 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
12b20 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
12b30 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
12b40 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
12b50 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
12b60 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
12b70 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
12b80 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
12b90 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
12ba0 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
12bb0 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
12bc0 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
12bd0 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
12be0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
12bf0 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
12c00 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
12c10 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73  exactly like "%s
12c20 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  " with the.** ad
12c30 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
12c40 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
12c50 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
12c60 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
12c70 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
12c80 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
12c90 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
12ca0 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a  t string. {END}.
12cb0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
12cc0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 33 7d  :.**.** {F17403}
12cd0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
12ce0 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73  printf()] and [s
12cf0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
12d00 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
12d10 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
12d20 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72  n either pointer
12d30 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
12d40 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
12d50 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20  gs held in.**   
12d60 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f          memory o
12d70 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
12d80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
12d90 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  or NULL pointers
12da0 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
12db0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
12dc0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61  te3_malloc()] fa
12dd0 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34  ils..**.** {F174
12de0 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  06}  The [sqlite
12df0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e  3_snprintf()] in
12e00 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20 61  terface writes a
12e10 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
12e20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55 54  .**           UT
12e30 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20  F-8 string into 
12e40 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74  the buffer point
12e50 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ed to by the sec
12e60 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
12e70 20 20 20 20 20 20 20 20 20 20 20 70 72 6f 76 69             provi
12e80 64 65 64 20 74 68 61 74 20 74 68 65 20 66 69 72  ded that the fir
12e90 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
12ea0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
12eb0 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 37  o..**.** {F17407
12ec0 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
12ed0 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  snprintf()] inte
12ee0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77  rface does not w
12ef0 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a  rite slots of.**
12f00 20 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6f             its o
12f10 75 74 70 75 74 20 62 75 66 66 65 72 20 28 74 68  utput buffer (th
12f20 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
12f30 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 65 20  er) outside the 
12f40 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  range.**        
12f50 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68 20     of 0 through 
12f60 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73 20  N-1 (where N is 
12f70 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
12f80 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  ter).**         
12f90 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20    regardless of 
12fa0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
12fb0 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  e string.**     
12fc0 20 20 20 20 20 20 72 65 71 75 65 73 74 65 64 20        requested 
12fd0 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70  by the format sp
12fe0 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a  ecification..*/.
12ff0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
13000 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
13010 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
13020 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
13030 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
13040 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
13050 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
13060 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
13070 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  r*, ...);../*.**
13080 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
13090 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
130a0 73 79 73 74 65 6d 20 7b 46 31 37 33 30 30 7d 0a  system {F17300}.
130b0 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
130c0 20 63 6f 72 65 20 20 75 73 65 73 20 74 68 65 73   core  uses thes
130d0 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
130e0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
130f0 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
13100 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13110 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20  n needs. "Core" 
13120 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
13130 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73  sentence.** does
13140 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65   not include ope
13150 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
13160 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65  ecific VFS imple
13170 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a  mentation.  The.
13180 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75  ** Windows VFS u
13190 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f  ses native mallo
131a0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
131b0 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f  or some operatio
131c0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
131d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
131e0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
131f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
13200 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
13210 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
13220 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
13230 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
13240 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c  meter..** If sql
13250 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
13260 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
13270 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
13280 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
13290 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
132a0 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20  ointer.  If the 
132b0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
132c0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
132d0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
132e0 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
132f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
13300 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
13310 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61  ointer..**.** Ca
13320 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
13330 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
13340 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
13350 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
13360 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
13370 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
13380 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
13390 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
133a0 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
133b0 72 65 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c  reused.  The sql
133c0 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
133d0 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
133e0 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
133f0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
13400 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
13410 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
13420 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
13430 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
13440 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
13450 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
13460 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
13470 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
13480 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
13490 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
134a0 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
134b0 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
134c0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
134d0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
134e0 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
134f0 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
13500 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
13510 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
13520 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
13530 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
13540 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
13550 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
13560 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
13570 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
13580 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
13590 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
135a0 69 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a 0a  ite3_free()..**.
135b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
135c0 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61  ealloc() interfa
135d0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
135e0 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
135f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13600 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73  on to be at leas
13610 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65  t N bytes, where
13620 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63   N is the.** sec
13630 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
13640 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
13650 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69  ation to be resi
13660 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74  zed is the first
13670 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20  .** parameter.  
13680 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
13690 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
136a0 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
136b0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
136c0 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
136d0 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
136e0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
136f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
13700 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
13710 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
13720 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
13730 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20  oc()..** If the 
13740 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
13750 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
13760 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
13770 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
13780 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
13790 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
137a0 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
137b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29   sqlite3_free(P)
137c0 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20   where P is the 
137d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
137e0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
137f0 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  oc()..** sqlite3
13800 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
13810 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
13820 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
13830 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
13840 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
13850 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
13860 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
13870 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
13880 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73  ** If M is the s
13890 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
138a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
138b0 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
138c0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
138d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
138e0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
138f0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
13900 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
13910 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
13920 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69  oc() and the pri
13930 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
13940 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71   freed..** If sq
13950 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
13960 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
13970 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
13980 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
13990 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  t freed..**.** T
139a0 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
139b0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
139c0 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
139d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
139e0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
139f0 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
13a00 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
13a10 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
13a20 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d  e default implem
13a30 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
13a40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13a50 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 73  n subsystem uses
13a60 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29  .** the malloc()
13a70 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
13a80 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 20  free() provided 
13a90 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  by the standard 
13aa0 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 46  C library..** {F
13ab0 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20  17382} However, 
13ac0 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
13ad0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
13ae0 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f  * SQLITE_MEMORY_
13af0 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20  SIZE=<i>NNN</i> 
13b00 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
13b10 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e  acro (where <i>N
13b20 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20  NN</i>.** is an 
13b30 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53  integer), then S
13b40 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73  QLite create a s
13b50 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20 61  tatic array of a
13b60 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e  t least.** <i>NN
13b70 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73  N</i> bytes in s
13b80 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68 61  ize and uses tha
13b90 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20  t array for all 
13ba0 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a  of its dynamic.*
13bb0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
13bc0 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d  ion needs. {END}
13bd0 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d    Additional mem
13be0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70  ory allocator op
13bf0 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20  tions.** may be 
13c00 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
13c10 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
13c20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
13c30 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
13c40 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
13c50 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
13c60 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
13c70 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
13c80 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
13c90 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
13ca0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
13cb0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
13cc0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
13cd0 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
13ce0 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
13cf0 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
13d00 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
13d10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
13d20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
13d30 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f  ** The Windows O
13d40 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
13d50 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
13d60 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
13d70 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
13d80 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
13d90 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
13da0 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
13db0 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
13dc0 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
13dd0 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
13de0 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
13df0 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
13e00 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
13e10 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
13e20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
13e30 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
13e40 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
13e50 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
13e60 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
13e70 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
13e80 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
13e90 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
13ea0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
13eb0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
13ec0 2a 2a 20 7b 46 31 37 33 30 33 7d 20 20 54 68 65  ** {F17303}  The
13ed0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13ee0 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (N)] interface r
13ef0 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20  eturns either a 
13f00 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20  pointer to.**   
13f10 20 20 20 20 20 20 20 20 61 20 6e 65 77 6c 79 20          a newly 
13f20 63 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63  checked-out bloc
13f30 6b 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  k of at least N 
13f40 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a  bytes of memory.
13f50 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61  **           tha
13f60 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67  t is 8-byte alig
13f70 6e 65 64 2c 20 6f 72 20 69 74 20 72 65 74 75 72  ned, or it retur
13f80 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73  ns NULL if it is
13f90 20 75 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20   unable.**      
13fa0 20 20 20 20 20 74 6f 20 66 75 6c 66 69 6c 6c 20       to fulfill 
13fb0 74 68 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a  the request..**.
13fc0 2a 2a 20 7b 46 31 37 33 30 34 7d 20 20 54 68 65  ** {F17304}  The
13fd0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13fe0 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (N)] interface r
13ff0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
14000 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20  inter if.**     
14010 20 20 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20        N is less 
14020 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
14030 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   zero..**.** {F1
14040 37 33 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69  7305}  The [sqli
14050 74 65 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74  te3_free(P)] int
14060 65 72 66 61 63 65 20 72 65 6c 65 61 73 65 73 20  erface releases 
14070 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c  memory previousl
14080 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  y.**           r
14090 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
140a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
140b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
140c0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  loc()],.**      
140d0 20 20 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61       making it a
140e0 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75  vailable for reu
140f0 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30  se..**.** {F1730
14100 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  6}  A call to [s
14110 71 6c 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c  qlite3_free(NULL
14120 29 5d 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  )] is a harmless
14130 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46   no-op..**.** {F
14140 31 37 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74  17310}  A call t
14150 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  o [sqlite3_reall
14160 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69  oc(0,N)] is equi
14170 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c  valent to a call
14180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f  .**           to
14190 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
141a0 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  (N)]..**.** {F17
141b0 33 31 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20  312}  A call to 
141c0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
141d0 28 50 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61  (P,0)] is equiva
141e0 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a  lent to a call.*
141f0 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b  *           to [
14200 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d  sqlite3_free(P)]
14210 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 35 7d  ..**.** {F17315}
14220 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
14230 65 20 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  e uses [sqlite3_
14240 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
14250 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a  te3_realloc()],.
14260 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6e 64  **           and
14270 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
14280 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  ] for all of its
14290 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
142a0 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  on and.**       
142b0 20 20 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e      deallocation
142c0 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46   needs..**.** {F
142d0 31 37 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c  17318}  The [sql
142e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
142f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
14300 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f  urns either a po
14310 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
14320 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66     to a block of
14330 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d   checked-out mem
14340 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ory of at least 
14350 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a  N bytes in size.
14360 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61  **           tha
14370 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67  t is 8-byte alig
14380 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ned, or a NULL p
14390 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ointer..**.** {F
143a0 31 37 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71  17321}  When [sq
143b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
143c0 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  N)] returns a no
143d0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
143e0 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  it first.**     
143f0 20 20 20 20 20 20 63 6f 70 69 65 73 20 74 68 65        copies the
14400 20 66 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f   first K bytes o
14410 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50  f content from P
14420 20 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 0a   into the newly.
14430 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6c 6c  **           all
14440 6f 63 61 74 65 64 20 62 6c 6f 63 6b 2c 20 77 68  ocated block, wh
14450 65 72 65 20 4b 20 69 73 20 74 68 65 20 6c 65 73  ere K is the les
14460 73 65 72 20 6f 66 20 4e 20 61 6e 64 20 74 68 65  ser of N and the
14470 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 20 20 20 20   size of.**     
14480 20 20 20 20 20 20 74 68 65 20 62 75 66 66 65 72        the buffer
14490 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32   P..**.** {F1732
144a0 32 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  2}  When [sqlite
144b0 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20  3_realloc(P,N)] 
144c0 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55  returns a non-NU
144d0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66  LL pointer, it f
144e0 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  irst.**         
144f0 20 20 72 65 6c 65 61 73 65 73 20 74 68 65 20 62    releases the b
14500 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b  uffer P..**.** {
14510 46 31 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73  F17323}  When [s
14520 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
14530 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c  ,N)] returns NUL
14540 4c 2c 20 74 68 65 20 62 75 66 66 65 72 20 50 20  L, the buffer P 
14550 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  is.**           
14560 6e 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20  not modified or 
14570 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
14580 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
14590 2a 2a 20 7b 55 31 37 33 35 30 7d 20 20 54 68 65  ** {U17350}  The
145a0 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
145b0 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
145c0 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
145d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
145e0 2a 20 20 20 20 20 20 20 20 20 20 20 6d 75 73 74  *           must
145f0 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
14600 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
14610 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
14620 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20   prior.**       
14630 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f      invocation o
14640 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
14650 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
14660 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
14670 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
14680 20 20 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20     not yet been 
14690 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
146a0 7b 55 31 37 33 35 31 7d 20 20 54 68 65 20 61 70  {U17351}  The ap
146b0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
146c0 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
146d0 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
146e0 20 20 20 20 20 20 20 20 20 20 61 20 62 6c 6f 63            a bloc
146f0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
14700 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
14710 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
14720 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
14730 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
14740 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14750 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
14760 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
14770 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
14780 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
14790 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
147a0 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
147b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
147c0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
147d0 53 74 61 74 69 73 74 69 63 73 20 7b 46 31 37 33  Statistics {F173
147e0 37 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  70}.**.** SQLite
147f0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
14800 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
14810 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
14820 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
14830 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
14840 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
14850 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
14860 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
14870 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
14880 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
14890 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
148a0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
148b0 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  tem..**.** INVAR
148c0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
148d0 37 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  7371} The [sqlit
148e0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
148f0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
14900 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
14910 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  bytes.**        
14920 20 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72    of memory curr
14930 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
14940 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
14950 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a  not freed)..**.*
14960 2a 20 7b 46 31 37 33 37 33 7d 20 54 68 65 20 5b  * {F17373} The [
14970 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
14980 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
14990 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
149a0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20  maximum.**      
149b0 20 20 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71      value of [sq
149c0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
149d0 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
149e0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
149f0 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20 6c  *          was l
14a00 61 73 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a  ast reset..**.**
14a10 20 7b 46 31 37 33 37 34 7d 20 54 68 65 20 76 61   {F17374} The va
14a20 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
14a30 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
14a40 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
14a50 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
14a60 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
14a70 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
14a80 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20 20  y overhead.**   
14a90 20 20 20 20 20 20 20 61 64 64 65 64 20 62 79 20         added by 
14aa0 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
14ab0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
14ac0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14ad0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
14ae0 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
14af0 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
14b00 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
14b10 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20  tem library.**  
14b20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 73          routines
14b30 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
14b40 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
14b50 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 35  l..**.** {F17375
14b60 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67  } The memory hig
14b70 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
14b80 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
14b90 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
14ba0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
14bb0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
14bc0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
14bd0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
14be0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
14bf0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
14c00 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
14c10 75 65 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72  ue.  The value r
14c20 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20  eturned.**      
14c30 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f      by [sqlite3_
14c40 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
14c50 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
14c60 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20  -water mark.**  
14c70 20 20 20 20 20 20 20 20 70 72 69 6f 72 20 74 6f          prior to
14c80 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73   the reset..*/.s
14c90 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
14ca0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
14cb0 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
14cc0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
14cd0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
14ce0 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
14cf0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14d00 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
14d10 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b  mber Generator {
14d20 46 31 37 33 39 30 7d 0a 2a 2a 0a 2a 2a 20 53 51  F17390}.**.** SQ
14d30 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
14d40 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
14d50 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
14d60 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
14d70 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
14d80 6c 65 63 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49  lect random ROWI
14d90 44 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  Ds when insertin
14da0 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
14db0 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
14dc0 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
14dd0 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
14de0 69 62 6c 65 20 52 4f 57 49 44 2e 20 20 54 68 65  ible ROWID.  The
14df0 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
14e00 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
14e10 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
14e20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
14e30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
14e40 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
14e50 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
14e60 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
14e70 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
14e80 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
14e90 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
14ea0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
14eb0 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
14ec0 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
14ed0 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a  o buffer P..**.*
14ee0 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65  * The first time
14ef0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
14f00 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72   invoked (either
14f10 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62   internally or b
14f20 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  y.** the applica
14f30 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69  tion) the PRNG i
14f40 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  s seeded using r
14f50 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
14f60 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78  ed.** from the x
14f70 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
14f80 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
14f90 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
14fa0 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c  bject..** On all
14fb0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
14fc0 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65  cations, the pse
14fd0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
14fe0 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
14ff0 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
15000 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
15010 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
15020 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
15030 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a  ** method..**.**
15040 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
15050 2a 2a 20 7b 46 31 37 33 39 32 7d 20 54 68 65 20  ** {F17392} The 
15060 5b 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e  [sqlite3_randomn
15070 65 73 73 28 4e 2c 50 29 5d 20 69 6e 74 65 72 66  ess(N,P)] interf
15080 61 63 65 20 77 72 69 74 65 73 20 4e 20 62 79 74  ace writes N byt
15090 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  es of.**        
150a0 20 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70    high-quality p
150b0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
150c0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
150d0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
150e0 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
150f0 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
15100 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
15110 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
15120 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
15130 73 20 7b 46 31 32 35 30 30 7d 0a 2a 2a 0a 2a 2a  s {F12500}.**.**
15140 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
15150 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72  gisters a author
15160 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
15170 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
15180 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
15190 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
151a0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
151b0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
151c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
151d0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
151e0 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
151f0 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
15200 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
15210 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
15220 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
15230 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
15240 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
15250 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
15260 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
15270 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41  pare16_v2()].  A
15280 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
15290 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
152a0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
152b0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
152c0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
152d0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
152e0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
152f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
15300 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
15310 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
15320 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
15330 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74  llowed.  The aut
15340 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
15350 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
15360 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
15370 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
15380 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
15390 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
153a0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
153b0 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
153c0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
153d0 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
153e0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
153f0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
15400 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
15410 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
15420 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
15430 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
15440 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61 75 74  ror.  If the aut
15450 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
15460 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
15470 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
15480 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
15490 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
154a0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
154b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
154c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
154d0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
154e0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
154f0 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
15500 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
15510 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
15520 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
15530 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
15540 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
15550 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
15560 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
15570 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
15580 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  .  When the call
15590 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
155a0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
155b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
155c0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
155d0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
155e0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
155f0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
15600 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
15610 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
15620 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
15630 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
15640 64 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f  d.  If the autho
15650 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53  rizer code is [S
15660 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
15670 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
15680 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
15690 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
156a0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
156b0 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
156c0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
156d0 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
156e0 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
156f0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
15700 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
15710 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
15720 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
15730 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
15740 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
15750 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
15760 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
15770 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
15780 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
15790 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
157a0 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
157b0 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a   of a table..**.
157c0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
157d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
157e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
157f0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
15800 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
15810 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
15820 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
15830 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
15840 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
15850 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
15860 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
15870 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
15880 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
15890 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
158a0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
158b0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
158c0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65   authorized. The
158d0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
158e0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
158f0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
15900 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
15910 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
15920 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
15930 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
15940 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
15950 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
15960 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  zed..**.** An au
15970 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
15980 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
15990 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
159a0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
159b0 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
159c0 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63  trusted.** sourc
159d0 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
159e0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
159f0 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72 79 20  ents do not try 
15a00 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 0a 2a  to access data.*
15a10 2a 20 74 68 61 74 20 74 68 65 79 20 61 72 65 20  * that they are 
15a20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
15a30 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
15a40 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a   do not try to.*
15a50 2a 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  * execute malici
15a60 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
15a70 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
15a80 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
15a90 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
15aa0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
15ab0 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
15ac0 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
15ad0 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
15ae0 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
15af0 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
15b00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
15b10 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
15b20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
15b30 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
15b40 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
15b50 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
15b60 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
15b70 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
15b80 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
15b90 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
15ba0 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
15bb0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
15bc0 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
15bd0 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
15be0 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
15bf0 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
15c00 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
15c10 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
15c20 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
15c30 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
15c40 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
15c50 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
15c60 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
15c70 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
15c80 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
15c90 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
15ca0 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
15cb0 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
15cc0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
15cd0 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
15ce0 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
15cf0 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
15d00 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  ** Only a single
15d10 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
15d20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
15d30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15d40 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
15d50 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
15d60 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
15d70 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
15d80 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
15d90 73 20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65  s call.  Disable
15da0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
15db0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
15dc0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
15dd0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
15de0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
15df0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e  default..**.** N
15e00 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
15e10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
15e20 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
15e30 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
15e40 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
15e50 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
15e60 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
15e70 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
15e80 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
15e90 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
15ea0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
15eb0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
15ec0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
15ed0 35 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  501} The [sqlite
15ee0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
15ef0 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  (D,...)] interfa
15f00 63 65 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a  ce registers a.*
15f10 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f  *          autho
15f20 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
15f30 69 74 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ith database con
15f40 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  nection D..**.**
15f50 20 7b 46 31 32 35 30 32 7d 20 54 68 65 20 61 75   {F12502} The au
15f60 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15f70 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
15f80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
15f90 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  re.**          b
15fa0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a  eing compiled..*
15fb0 2a 0a 2a 2a 20 7b 46 31 32 35 30 33 7d 20 49 66  *.** {F12503} If
15fc0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
15fd0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
15fe0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
15ff0 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20   than.**        
16000 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45    [SQLITE_IGNORE
16010 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
16020 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
16030 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
16040 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
16050 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
16060 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
16070 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
16080 20 20 20 20 20 20 20 20 20 74 68 65 20 61 75 74           the aut
16090 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
160a0 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61   to run shall fa
160b0 69 6c 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20  il with an.**   
160c0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45         [SQLITE_E
160d0 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65  RROR] error code
160e0 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69   and an appropri
160f0 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ate error messag
16100 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 34  e..**.** {F12504
16110 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f  } When the autho
16120 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
16130 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
16140 4b 5d 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  K], the operatio
16150 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  n.**          de
16160 73 63 72 69 62 65 64 20 69 73 20 70 72 6f 63 65  scribed is proce
16170 73 73 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a  ssed normally..*
16180 2a 0a 2a 2a 20 7b 46 31 32 35 30 35 7d 20 57 68  *.** {F12505} Wh
16190 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  en the authorize
161a0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
161b0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
161c0 2c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  , the.**        
161d0 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
161e0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
161f0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
16200 20 63 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20   caused the.**  
16210 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a          authoriz
16220 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72  er callback to r
16230 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a  un shall fail.**
16240 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 61            with a
16250 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
16260 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
16270 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
16280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 70  .**          exp
16290 6c 61 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63  laining that acc
162a0 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a  ess is denied..*
162b0 2a 0a 2a 2a 20 7b 46 31 32 35 30 36 7d 20 49 66  *.** {F12506} If
162c0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
162d0 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61  code (the 2nd pa
162e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
162f0 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20  uthorizer.**    
16300 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20        callback) 
16310 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
16320 20 61 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69   and the authori
16330 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
16340 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
16350 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
16360 2c 20 74 68 65 6e 20 74 68 65 20 70 72 65 70 61  , then the prepa
16370 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
16380 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 0a   constructed to.
16390 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 65  **          inse
163a0 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  rt a NULL value 
163b0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
163c0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
163d0 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
163e0 20 20 20 20 20 20 20 20 20 62 65 65 6e 20 72 65           been re
163f0 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
16400 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
16410 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  ned..**.** {F125
16420 30 37 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f  07} If the autho
16430 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20  rizer code (the 
16440 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
16450 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a   the authorizer.
16460 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
16470 62 61 63 6b 29 20 69 73 20 61 6e 79 74 68 69 6e  back) is anythin
16480 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
16490 4c 49 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e  LITE_READ], then
164a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72  .**          a r
164b0 65 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45  eturn of [SQLITE
164c0 5f 49 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65  _IGNORE] has the
164d0 20 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20   same effect as 
164e0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 2a  [SQLITE_DENY]..*
164f0 2a 0a 2a 2a 20 7b 46 31 32 35 31 30 7d 20 54 68  *.** {F12510} Th
16500 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
16510 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
16520 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
16530 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20  a copy of.**    
16540 20 20 20 20 20 20 74 68 65 20 74 68 69 72 64 20        the third 
16550 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
16560 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
16570 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
16580 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  rface..**.** {F1
16590 32 35 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64  2511} The second
165a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
165b0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
165c0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20   integer.**     
165d0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50       [SQLITE_COP
165e0 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
165f0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
16600 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
16610 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
16620 20 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a    to be authoriz
16630 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31  ed..**.** {F1251
16640 32 7d 20 54 68 65 20 74 68 69 72 64 20 74 68 72  2} The third thr
16650 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
16660 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c  eters to the cal
16670 6c 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20  lback are.**    
16680 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
16690 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
166a0 61 74 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20  at contain.**   
166b0 20 20 20 20 20 20 20 61 64 64 69 74 69 6f 6e 61         additiona
166c0 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  l details about 
166d0 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
166e0 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
166f0 2a 2a 20 7b 46 31 32 35 32 30 7d 20 45 61 63 68  ** {F12520} Each
16700 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
16710 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
16720 28 29 5d 20 6f 76 65 72 72 69 64 65 73 0a 2a 2a  ()] overrides.**
16730 20 20 20 20 20 20 20 20 20 20 61 6e 79 20 70 72            any pr
16740 65 76 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c  eviously install
16750 65 64 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  ed authorizer..*
16760 2a 0a 2a 2a 20 7b 46 31 32 35 32 31 7d 20 41 20  *.** {F12521} A 
16770 4e 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20  NULL authorizer 
16780 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75  means that no au
16790 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20  thorization.**  
167a0 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
167b0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
167c0 2a 2a 20 7b 46 31 32 35 32 32 7d 20 54 68 65 20  ** {F12522} The 
167d0 64 65 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a  default authoriz
167e0 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  er is NULL..*/.i
167f0 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
16800 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
16810 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
16820 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
16830 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
16840 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
16850 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
16860 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
16870 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
16880 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
16890 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20  er Return Codes 
168a0 7b 46 31 32 35 39 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12590}.**.** T
168b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
168c0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
168d0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
168e0 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
168f0 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
16900 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
16910 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
16920 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
16930 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
16940 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
16950 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
16960 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
16970 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
16980 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
16990 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
169a0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
169b0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
169c0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
169d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
169e0 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
169f0 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
16a00 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
16a10 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
16a20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
16a30 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
16a40 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
16a50 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
16a60 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
16a70 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
16a80 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
16a90 20 7b 46 31 32 35 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F12550}.**.** 
16aa0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
16ab0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
16ac0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
16ad0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
16ae0 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
16af0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
16b00 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
16b10 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
16b20 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
16b30 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
16b40 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
16b50 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
16b60 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
16b70 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
16b80 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
16b90 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
16ba0 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
16bb0 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
16bc0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
16bd0 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
16be0 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
16bf0 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
16c00 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
16c10 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
16c20 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
16c30 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
16c40 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
16c50 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
16c60 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
16c70 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
16c80 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
16c90 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
16ca0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
16cb0 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
16cc0 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
16cd0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16ce0 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61  ter.  The 5th pa
16cf0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
16d00 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
16d10 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
16d20 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
16d30 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
16d40 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
16d50 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20  pplicable.  The 
16d60 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
16d70 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
16d80 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
16d90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
16da0 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
16db0 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
16dc0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
16dd0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
16de0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
16df0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
16e00 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
16e10 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
16e20 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
16e30 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
16e40 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 31 7d 20  .**.** {F12551} 
16e50 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16e60 65 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 20  eter to an.**   
16e70 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
16e80 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
16e90 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16ea0 62 61 63 6b 5d 20 69 73 20 61 6c 77 61 79 73 20  back] is always 
16eb0 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20  an integer.**   
16ec0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43         [SQLITE_C
16ed0 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  OPY | authorizer
16ee0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
16ef0 69 66 69 65 73 20 77 68 61 74 20 61 63 74 69 6f  ifies what actio
16f00 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  n.**          is
16f10 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
16f20 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 32  d..**.** {F12552
16f30 7d 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74  } The 3rd and 4t
16f40 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
16f50 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
16f60 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
16f70 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
16f80 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  ization callback
16f90 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
16fa0 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
16fb0 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
16fc0 6e 67 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 20  ng on which.**  
16fd0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
16fe0 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65  COPY | authorize
16ff0 72 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64 20  r code] is used 
17000 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
17010 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
17020 46 31 32 35 35 33 7d 20 54 68 65 20 35 74 68 20  F12553} The 5th 
17030 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
17040 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
17050 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
17060 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
17070 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74  r callback] is t
17080 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he name.**      
17090 20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61 62      of the datab
170a0 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d  ase (example: "m
170b0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74  ain", "temp", et
170c0 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
170d0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 34  e..**.** {F12554
170e0 7d 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65  } The 6th parame
170f0 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ter to the.**   
17100 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
17110 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
17120 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17130 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d  back] is the nam
17140 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
17150 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
17160 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
17170 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
17180 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ble for.**      
17190 20 20 20 20 74 68 65 20 61 63 63 65 73 73 20 61      the access a
171a0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
171b0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
171c0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
171d0 79 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20  y from.**       
171e0 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c     top-level SQL
171f0 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
17200 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17210 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17220 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
17230 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
17240 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
17250 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
17260 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
17270 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
17280 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
17290 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
172a0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
172b0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
172c0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
172d0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
172e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
172f0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
17300 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
17310 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
17320 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
17330 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17340 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
17350 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
17360 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
17370 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
17380 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17390 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
173a0 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
173b0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
173c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
173d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
173e0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
173f0 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
17400 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
17410 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17420 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17430 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
17440 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
17450 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
17460 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
17470 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17480 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
17490 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
174a0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
174b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
174c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
174d0 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
174e0 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
174f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
17500 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17510 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17520 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
17530 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
17540 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
17550 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
17560 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
17570 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
17580 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
17590 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
175a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
175b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
175c0 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
175d0 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
175e0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
175f0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
17600 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
17610 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
17620 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
17630 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
17640 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17650 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
17660 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
17670 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
17680 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
17690 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
176a0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
176b0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
176c0 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
176d0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
176e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
176f0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
17700 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
17710 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
17720 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
17730 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17740 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
17750 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
17760 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
17770 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
17780 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17790 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
177a0 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
177b0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
177c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
177d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
177e0 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
177f0 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
17800 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
17810 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
17820 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
17830 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
17840 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
17850 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
17860 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
17870 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17880 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
17890 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
178a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
178b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
178c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
178d0 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
178e0 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
178f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17900 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17910 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17920 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
17930 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
17940 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
17950 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
17960 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17970 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
17980 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
17990 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
179a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
179b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
179c0 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
179d0 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
179e0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
179f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17a00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
17a10 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
17a20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
17a30 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
17a40 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
17a50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
17a60 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
17a70 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
17a80 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
17a90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
17aa0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
17ab0 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
17ac0 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
17ad0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
17ae0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
17af0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
17b00 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
17b10 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
17b20 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
17b30 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
17b40 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
17b50 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
17b60 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
17b70 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
17b80 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
17b90 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
17ba0 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
17bb0 31 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20  1   /* Function 
17bc0 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
17bd0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
17be0 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
17bf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
17c00 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
17c10 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
17c20 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
17c30 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
17c40 75 6e 63 74 69 6f 6e 73 20 7b 46 31 32 32 38 30  unctions {F12280
17c50 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
17c60 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
17c70 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
17c80 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
17c90 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
17ca0 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
17cb0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
17cc0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
17cd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
17ce0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
17cf0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
17d00 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
17d10 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
17d20 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
17d30 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
17d40 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
17d50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
17d60 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  ]..** The callba
17d70 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54 46  ck returns a UTF
17d80 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
17d90 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
17da0 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65  t text.** as the
17db0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
17dc0 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
17dd0 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63  g.  Additional c
17de0 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a  allbacks occur.*
17df0 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
17e00 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
17e10 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
17e20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
17e30 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
17e40 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
17e50 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
17e60 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
17e70 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  r..**.** The cal
17e80 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
17e90 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
17ea0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
17eb0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
17ec0 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
17ed0 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68  nt finishes.  Th
17ee0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
17ef0 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
17f00 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
17f10 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
17f20 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
17f30 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
17f40 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
17f50 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
17f60 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54   to run..**.** T
17f70 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  he sqlite3_profi
17f80 6c 65 28 29 20 41 50 49 20 69 73 20 63 75 72 72  le() API is curr
17f90 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
17fa0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
17fb0 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63 74 20  d.** is subject 
17fc0 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d  to change or rem
17fd0 6f 76 61 6c 20 69 6e 20 61 20 66 75 74 75 72 65  oval in a future
17fe0 20 72 65 6c 65 61 73 65 2e 0a 2a 2a 0a 2a 2a 20   release..**.** 
17ff0 54 68 65 20 74 72 69 67 67 65 72 20 72 65 70 6f  The trigger repo
18000 72 74 69 6e 67 20 66 65 61 74 75 72 65 20 6f 66  rting feature of
18010 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
18020 61 63 6b 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ack is considere
18030 64 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61  d.** experimenta
18040 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74  l and is subject
18050 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65   to change or re
18060 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20  moval in future 
18070 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 20 46 75 74  releases..** Fut
18080 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
18090 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
180a0 6f 20 61 64 64 20 6e 65 77 20 74 72 61 63 65 20  o add new trace 
180b0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6e 76 6f  callback.** invo
180c0 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  cations..**.** I
180d0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
180e0 20 7b 46 31 32 32 38 31 7d 20 54 68 65 20 63 61   {F12281} The ca
180f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
18100 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73  registered by [s
18110 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
18120 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  is.**          w
18130 68 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20 73  henever an SQL s
18140 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
18150 65 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74 65  egins to execute
18160 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
18170 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 69 67   whenever a trig
18180 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20 66  ger subprogram f
18190 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 72  irst begins to r
181a0 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38  un..**.** {F1228
181b0 32 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  2} Each call to 
181c0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
181d0 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20  ] overrides the 
181e0 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20  previously.**   
181f0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
18200 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  d trace callback
18210 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 33 7d  ..**.** {F12283}
18220 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63 61   A NULL trace ca
18230 6c 6c 62 61 63 6b 20 64 69 73 61 62 6c 65 73 20  llback disables 
18240 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  tracing..**.** {
18250 46 31 32 32 38 34 7d 20 54 68 65 20 66 69 72 73  F12284} The firs
18260 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
18270 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
18280 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
18290 20 20 20 20 20 20 20 20 20 20 74 68 65 20 70 6f            the po
182a0 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
182b0 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  the 3rd argument
182c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
182d0 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ce()]..**.** {F1
182e0 32 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e 64  2285} The second
182f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
18300 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
18310 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
18320 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
18330 20 55 54 46 38 20 73 74 72 69 6e 67 20 63 6f 6e   UTF8 string con
18340 74 61 69 6e 69 6e 67 20 74 68 65 20 6f 72 69 67  taining the orig
18350 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20 20  inal text.**    
18360 20 20 20 20 20 20 6f 66 20 74 68 65 20 53 51 4c        of the SQL
18370 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74   statement as it
18380 20 77 61 73 20 70 61 73 73 65 64 20 69 6e 74 6f   was passed into
18390 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
183a0 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20  e_v2()].**      
183b0 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 76      or the equiv
183c0 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51 4c  alent, or an SQL
183d0 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61 74   comment indicat
183e0 69 6e 67 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  ing the beginnin
183f0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  g.**          of
18400 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72   a trigger subpr
18410 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ogram..**.** {F1
18420 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c 62 61  2287} The callba
18430 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
18440 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74  stered by [sqlit
18450 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69 73  e3_profile()] is
18460 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20   invoked.**     
18470 20 20 20 20 20 61 73 20 65 61 63 68 20 53 51 4c       as each SQL
18480 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
18490 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  hes..**.** {F122
184a0 38 38 7d 20 54 68 65 20 66 69 72 73 74 20 70 61  88} The first pa
184b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70  rameter to the p
184c0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
184d0 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  is a copy of.** 
184e0 20 20 20 20 20 20 20 20 20 74 68 65 20 33 72 64           the 3rd
184f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
18500 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
18510 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 39  ]..**.** {F12289
18520 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  } The second par
18530 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72  ameter to the pr
18540 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69  ofile callback i
18550 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
18560 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
18570 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 61  UTF-8 string tha
18580 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 63  t contains the c
18590 6f 6d 70 6c 65 74 65 20 74 65 78 74 20 6f 66 0a  omplete text of.
185a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
185b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
185c0 20 69 74 20 77 61 73 20 70 72 6f 63 65 73 73 65   it was processe
185d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  d by [sqlite3_pr
185e0 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20  epare_v2()].**  
185f0 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 65          or the e
18600 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a  quivalent..**.**
18610 20 7b 46 31 32 32 39 30 7d 20 54 68 65 20 74 68   {F12290} The th
18620 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
18630 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c   the profile cal
18640 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73 74 69  lback is an esti
18650 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  mate.**         
18660 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
18670 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66  f nanoseconds of
18680 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
18690 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a 20   required to.** 
186a0 20 20 20 20 20 20 20 20 20 72 75 6e 20 74 68 65           run the
186b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
186c0 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66 69 6e  rom start to fin
186d0 69 73 68 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ish..*/.void *sq
186e0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
186f0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
18700 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
18710 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
18720 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
18730 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
18740 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
18750 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
18760 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
18770 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
18780 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
18790 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
187a0 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 31 30 7d  llbacks {F12910}
187b0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
187c0 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61  ine configures a
187d0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
187e0 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67  on - the.** prog
187f0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20  ress callback - 
18800 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
18810 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
18820 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e  ing long.** runn
18830 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ing calls to [sq
18840 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
18850 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
18860 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
18870 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41  get_table()].  A
18880 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
18890 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
188a0 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
188b0 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
188c0 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
188d0 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  y..**.** If the 
188e0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
188f0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
18900 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
18910 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
18920 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
18930 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
18940 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
18950 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
18960 20 6f 6e 20 61 20 47 55 49 20 64 69 61 6c 6f 67   on a GUI dialog
18970 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   box..**.** INVA
18980 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
18990 31 32 39 31 31 7d 20 54 68 65 20 63 61 6c 6c 62  12911} The callb
189a0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
189b0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
189c0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
189d0 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20  ler().**        
189e0 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72    is invoked per
189f0 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
18a00 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
18a10 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  lls to.**       
18a20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70     [sqlite3_step
18a30 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ()]..**.** {F129
18a40 31 32 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73  12} The progress
18a50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
18a60 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76  oked once for ev
18a70 65 72 79 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a  ery N virtual.**
18a80 20 20 20 20 20 20 20 20 20 20 6d 61 63 68 69 6e            machin
18a90 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65 72 65  e opcodes, where
18aa0 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
18ab0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
18ac0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
18ad0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
18ae0 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74  andler()] call t
18af0 68 61 74 20 72 65 67 69 73 74 65 72 65 64 0a 2a  hat registered.*
18b00 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
18b10 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 4e 20 69  allback.  If N i
18b20 73 20 6c 65 73 73 20 74 68 61 6e 20 31 2c 20 73  s less than 1, s
18b30 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
18b40 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20  handler().**    
18b50 20 20 20 20 20 20 61 63 74 73 20 61 73 20 69 66        acts as if
18b60 20 61 20 4e 55 4c 4c 20 70 72 6f 67 72 65 73 73   a NULL progress
18b70 20 68 61 6e 64 6c 65 72 20 68 61 64 20 62 65 65   handler had bee
18b80 6e 20 73 70 65 63 69 66 69 65 64 2e 0a 2a 2a 0a  n specified..**.
18b90 2a 2a 20 7b 46 31 32 39 31 33 7d 20 54 68 65 20  ** {F12913} The 
18ba0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
18bb0 6b 20 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e  k itself is iden
18bc0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 74 68  tified by the th
18bd0 69 72 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ird.**          
18be0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
18bf0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
18c00 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46  dler()..**.** {F
18c10 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75 72 74  12914} The fourt
18c20 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
18c30 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
18c40 61 6e 64 6c 65 72 28 29 20 69 73 20 61 0a 2a 2a  andler() is a.**
18c50 2a 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 70  *         void p
18c60 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f  ointer passed to
18c70 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
18c80 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
18c90 20 20 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68     function each
18ca0 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f   time it is invo
18cb0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ked..**.** {F129
18cc0 31 35 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f  15} If a call to
18cd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
18ce0 5d 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77  ] results in few
18cf0 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
18d00 20 20 20 20 4e 20 6f 70 63 6f 64 65 73 20 62 65      N opcodes be
18d10 69 6e 67 20 65 78 65 63 75 74 65 64 2c 0a 2a 2a  ing executed,.**
18d20 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
18d30 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
18d40 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e  back is never in
18d50 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  voked. {END}.**.
18d60 2a 2a 20 7b 46 31 32 39 31 36 7d 20 45 76 65 72  ** {F12916} Ever
18d70 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  y call to [sqlit
18d80 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
18d90 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ler()].**       
18da0 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e     overwrites an
18db0 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  y previously reg
18dc0 69 73 74 65 72 65 64 20 70 72 6f 67 72 65 73 73  istered progress
18dd0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
18de0 7b 46 31 32 39 31 37 7d 20 49 66 20 74 68 65 20  {F12917} If the 
18df0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
18e00 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
18e10 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65  L then no progre
18e20 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  ss.**          h
18e30 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65  andler is invoke
18e40 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 38  d..**.** {F12918
18e50 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73  } If the progres
18e60 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
18e70 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65  ns a result othe
18e80 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a  r than 0, then.*
18e90 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
18ea0 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 66 20  ehavior is a if 
18eb0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
18ec0 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63  pt()] had been c
18ed0 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  alled..*/.void s
18ee0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
18ef0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
18f00 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
18f10 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
18f20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
18f30 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
18f40 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
18f50 20 7b 46 31 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F12700}.**.** 
18f60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
18f70 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
18f80 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73  tabase file whos
18f90 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20  e name is given 
18fa0 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  by the.** filena
18fb0 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65  me argument. The
18fc0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
18fd0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
18fe0 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
18ff0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
19000 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
19010 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
19020 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
19030 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
19040 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
19050 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61  n16(). A [databa
19060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
19070 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
19080 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
19090 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
190a0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
190b0 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
190c0 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
190d0 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
190e0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
190f0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
19100 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
19110 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
19120 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
19130 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
19140 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
19150 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
19160 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65  * object. If the
19170 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
19180 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
19190 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
191a0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
191b0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
191c0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
191d0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
191e0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
191f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
19200 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
19210 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
19220 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
19230 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
19240 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
19250 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
19260 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a   of the error..*
19270 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
19280 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
19290 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
192a0 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
192b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
192c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
192d0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
192e0 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
192f0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
19300 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
19310 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
19320 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
19330 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
19340 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
19350 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
19360 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
19370 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
19380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
19390 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
193a0 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
193b0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
193c0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
193d0 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
193e0 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
193f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
19400 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
19410 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
19420 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
19430 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
19440 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
19450 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
19460 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
19470 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
19480 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
19490 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
194a0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
194b0 74 65 72 20 63 61 6e 20 62 65 20 6f 6e 65 20 6f  ter can be one o
194c0 66 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  f:.**.** <dl>.**
194d0 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
194e0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
194f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
19500 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
19510 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
19520 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
19530 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
19540 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
19550 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
19560 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
19570 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
19580 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
19590 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
195a0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
195b0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
195c0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
195d0 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
195e0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
195f0 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
19600 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
19610 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
19620 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
19630 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
19640 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
19650 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
19660 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
19670 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
19680 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
19690 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
196a0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
196b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
196c0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
196d0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
196e0 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
196f0 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69 66  is creates it if
19700 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
19710 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
19720 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
19730 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
19740 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
19750 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
19760 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
19770 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  ().</dd>.** </dl
19780 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
19790 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
197a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
197b0 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
197c0 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
197d0 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
197e0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
197f0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
19800 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
19810 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
19820 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
19830 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
19840 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
19850 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
19860 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
19870 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d  on.  This in-mem
19880 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
19890 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
198a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
198b0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
198c0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
198d0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
198e0 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
198f0 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
19900 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
19910 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
19920 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
19930 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
19940 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
19950 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
19960 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
19970 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
19980 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
19990 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
199a0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
199b0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
199c0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
199d0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
199e0 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uity..**.** If t
199f0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
19a00 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
19a10 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
19a20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
19a30 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
19a40 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
19a50 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
19a60 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
19a70 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
19a80 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
19a90 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
19aa0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
19ab0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  sed..**.** The f
19ac0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
19ad0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
19ae0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
19af0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
19b00 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
19b10 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
19b20 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
19b30 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
19b40 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
19b50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19b60 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20  should use.  If 
19b70 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
19b80 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
19b90 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
19ba0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
19bb0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
19bc0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
19bd0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
19be0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
19bf0 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
19c00 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
19c10 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
19c20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
19c30 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
19c40 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
19c50 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
19c60 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
19c70 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
19c80 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
19c90 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
19ca0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
19cb0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
19cc0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
19cd0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
19ce0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
19cf0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
19d00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
19d10 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  )..**.** INVARIA
19d20 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  NTS:.**.** {F127
19d30 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
19d40 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
19d50 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
19d60 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
19d70 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19d80 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63 72 65  ] interfaces cre
19d90 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20  ate a new.**    
19da0 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
19db0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f  connection] asso
19dc0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20  ciated with.**  
19dd0 20 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61          the data
19de0 62 61 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20  base file given 
19df0 69 6e 20 74 68 65 69 72 20 66 69 72 73 74 20 70  in their first p
19e00 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
19e10 7b 46 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c  {F12702} The fil
19e20 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
19e30 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
19e40 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20   UTF-8.**       
19e50 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f     for [sqlite3_
19e60 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  open()] and [sql
19e70 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
19e80 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a  and as UTF-16.**
19e90 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65            in the
19ea0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
19eb0 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f  er for [sqlite3_
19ec0 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  open16()]..**.**
19ed0 20 7b 46 31 32 37 30 33 7d 20 41 20 73 75 63 63   {F12703} A succ
19ee0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
19ef0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  n of [sqlite3_op
19f00 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
19f10 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20  open16()],.**   
19f20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
19f30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72  e3_open_v2()] wr
19f40 69 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ites a pointer t
19f50 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20  o a new.**      
19f60 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
19f70 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a  nnection] into *
19f80 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ppDb..**.** {F12
19f90 37 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  704} The [sqlite
19fa0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
19fb0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
19fc0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
19fd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
19fe0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  )] interfaces re
19ff0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1a000 20 75 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a   upon success,.*
1a010 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e  *          or an
1a020 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
1a030 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69  ror code] on fai
1a040 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  lure..**.** {F12
1a050 37 30 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74  706} The default
1a060 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66   text encoding f
1a070 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73  or a new databas
1a080 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  e created using.
1a090 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1a0a0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
1a0b0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1a0c0 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ()] will be UTF-
1a0d0 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 37  8..**.** {F12707
1a0e0 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65  } The default te
1a0f0 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  xt encoding for 
1a100 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  a new database c
1a110 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
1a120 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1a130 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c  3_open16()] will
1a140 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a   be UTF-16..**.*
1a150 2a 20 7b 46 31 32 37 30 39 7d 20 54 68 65 20 5b  * {F12709} The [
1a160 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44  sqlite3_open(F,D
1a170 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  )] interface is 
1a180 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a  equivalent to.**
1a190 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1a1a0 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1a1b0 2c 30 29 5d 20 77 68 65 72 65 20 74 68 65 20 47  ,0)] where the G
1a1c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1a1d0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
1a1e0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1a1f0 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ]|[SQLITE_OPEN_C
1a200 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  REATE]..**.** {F
1a210 31 32 37 31 31 7d 20 49 66 20 74 68 65 20 47 20  12711} If the G 
1a220 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1a230 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
1a240 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73  D,G,V)] contains
1a250 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1a260 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49   bit value [SQLI
1a270 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1a280 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  ] then the datab
1a290 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a  ase is opened.**
1a2a0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 72 65            for re
1a2b0 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ading only..**.*
1a2c0 2a 20 7b 46 31 32 37 31 32 7d 20 49 66 20 74 68  * {F12712} If th
1a2d0 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
1a2e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1a2f0 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74  2(F,D,G,V)] cont
1a300 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ains the.**     
1a310 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
1a320 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1a330 57 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20  WRITE] then the 
1a340 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1a350 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ed.**          r
1a360 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1a370 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
1a380 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f  or for reading o
1a390 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20  nly if the.**   
1a3a0 20 20 20 20 20 20 20 66 69 6c 65 20 69 73 20 77         file is w
1a3b0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
1a3c0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
1a3d0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  system..**.** {F
1a3e0 31 32 37 31 33 7d 20 49 66 20 74 68 65 20 47 20  12713} If the G 
1a3f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1a400 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c  lite3_open(v2(F,
1a410 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68  D,G,V)] omits th
1a420 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
1a430 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
1a440 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64  OPEN_CREATE] and
1a450 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1a460 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20  es not.**       
1a470 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78     previously ex
1a480 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1a490 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1a4a0 20 7b 46 31 32 37 31 34 7d 20 49 66 20 74 68 65   {F12714} If the
1a4b0 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
1a4c0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32  [sqlite3_open(v2
1a4d0 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61  (F,D,G,V)] conta
1a4e0 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ins the.**      
1a4f0 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
1a500 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1a510 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  E] and the datab
1a520 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
1a530 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75           previou
1a540 73 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20  sly exist, then 
1a550 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
1a560 64 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64  de to create and
1a570 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69  .**          ini
1a580 74 69 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61  tialize the data
1a590 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  base..**.** {F12
1a5a0 37 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65  717} If the file
1a5b0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  name argument to
1a5c0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1a5d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1a5e0 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  16()],.**       
1a5f0 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f     or [sqlite3_o
1a600 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d  pen_v2()] is ":m
1a610 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e  emory:", then an
1a620 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20   private,.**    
1a630 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c        ephemeral,
1a640 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1a650 61 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66  ase is created f
1a660 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1a670 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c  n..**          <
1a680 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f  todo>Is SQLITE_O
1a690 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54  PEN_CREATE|SQLIT
1a6a0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1a6b0 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20   required.**    
1a6c0 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33        in sqlite3
1a6d0 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64  _open_v2()?</tod
1a6e0 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 39  o>.**.** {F12719
1a6f0 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  } If the filenam
1a700 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  e is NULL or an 
1a710 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
1a720 65 6e 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a  en a private,.**
1a730 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65            epheme
1a740 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  ral on-disk data
1a750 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
1a760 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20  ated..**        
1a770 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54    <todo>Is SQLIT
1a780 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51  E_OPEN_CREATE|SQ
1a790 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1a7a0 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20  ITE required.** 
1a7b0 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69           in sqli
1a7c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f  te3_open_v2()?</
1a7d0 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  todo>.**.** {F12
1a7e0 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61  721} The [databa
1a7f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63  se connection] c
1a800 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  reated by [sqlit
1a810 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1a820 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,V)].**         
1a830 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 5b 73   will use the [s
1a840 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1a850 63 74 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  ct identified by
1a860 20 74 68 65 20 56 20 70 61 72 61 6d 65 74 65 72   the V parameter
1a870 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
1a880 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1a890 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1a8a0 74 20 69 66 20 56 20 69 73 20 61 20 4e 55 4c 4c  t if V is a NULL
1a8b0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1a8c0 7b 46 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61  {F12723} Two [da
1a8d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a8e0 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72 65 20 61  ns] will share a
1a8f0 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69 66   common cache if
1a900 20 62 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20 20   both were.**   
1a910 20 20 20 20 20 20 20 6f 70 65 6e 65 64 20 77 69         opened wi
1a920 74 68 20 74 68 65 20 73 61 6d 65 20 56 46 53 20  th the same VFS 
1a930 77 68 69 6c 65 20 5b 73 68 61 72 65 64 20 63 61  while [shared ca
1a940 63 68 65 20 6d 6f 64 65 5d 20 77 61 73 20 65 6e  che mode] was en
1a950 61 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20 20  abled and.**    
1a960 20 20 20 20 20 20 69 66 20 62 6f 74 68 20 66 69        if both fi
1a970 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20  lenames compare 
1a980 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63  equal using memc
1a990 6d 70 28 29 20 61 66 74 65 72 20 68 61 76 69 6e  mp() after havin
1a9a0 67 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20  g been.**       
1a9b0 20 20 20 70 72 6f 63 65 73 73 65 64 20 62 79 20     processed by 
1a9c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1a9d0 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   | xFullPathname
1a9e0 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
1a9f0 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  VFS..*/.int sqli
1aa00 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
1aa10 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1aa20 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1aa30 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1aa40 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1aa50 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1aa60 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1aa70 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1aa80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1aa90 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
1aaa0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1aab0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1aac0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
1aad0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1aae0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1aaf0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1ab00 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1ab10 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
1ab20 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1ab30 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1ab40 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1ab50 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1ab60 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
1ab70 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1ab80 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
1ab90 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
1aba0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
1abb0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
1abc0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
1abd0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
1abe0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
1abf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
1ac00 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
1ac10 73 73 61 67 65 73 20 7b 46 31 32 38 30 30 7d 0a  ssages {F12800}.
1ac20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1ac30 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
1ac40 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1ac50 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
1ac60 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
1ac70 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1ac80 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1ac90 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
1aca0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
1acb0 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
1acc0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
1acd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
1ace0 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
1acf0 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
1ad00 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1ad10 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
1ad20 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
1ad30 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
1ad40 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1ad50 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
1ad60 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1ad70 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
1ad80 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
1ad90 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
1ada0 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
1adb0 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
1adc0 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
1add0 68 65 72 20 55 54 46 38 20 6f 72 20 55 54 46 31  her UTF8 or UTF1
1ade0 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
1adf0 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** Memory to hol
1ae00 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
1ae10 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
1ae20 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
1ae30 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
1ae40 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
1ae50 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
1ae60 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
1ae70 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
1ae80 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
1ae90 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
1aea0 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
1aeb0 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
1aec0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1aed0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
1aee0 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
1aef0 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
1af00 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38  NTS:.**.** {F128
1af10 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
1af20 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e 74  _errcode(D)] int
1af30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
1af40 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20  he numeric.**   
1af50 20 20 20 20 20 20 20 5b 72 65 73 75 6c 74 20 63         [result c
1af60 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
1af70 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
1af80 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
1af90 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ntly.**         
1afa0 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63   failed interfac
1afb0 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  e call associate
1afc0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
1afd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1afe0 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30   D..**.** {F1280
1aff0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
1b000 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64 20 5b  errmsg(D)] and [
1b010 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1b020 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (D)].**         
1b030 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
1b040 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
1b050 61 67 65 20 74 65 78 74 20 74 68 61 74 20 64 65  age text that de
1b060 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20 20 20  scribes.**      
1b070 20 20 20 20 74 68 65 20 65 72 72 6f 72 20 69 6e      the error in
1b080 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65 63 65   the mostly rece
1b090 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74 65  ntly failed inte
1b0a0 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20  rface call,.**  
1b0b0 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64 20          encoded 
1b0c0 61 73 20 65 69 74 68 65 72 20 55 54 46 38 20 6f  as either UTF8 o
1b0d0 72 20 55 54 46 31 36 20 72 65 73 70 65 63 74 69  r UTF16 respecti
1b0e0 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  vely..**.** {F12
1b0f0 38 30 37 7d 20 54 68 65 20 73 74 72 69 6e 67 73  807} The strings
1b100 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1b110 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
1b120 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
1b130 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  msg16()].**     
1b140 20 20 20 20 20 61 72 65 20 76 61 6c 69 64 20 75       are valid u
1b150 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 53 51  ntil the next SQ
1b160 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 63  Lite interface c
1b170 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38  all..**.** {F128
1b180 30 38 7d 20 43 61 6c 6c 73 20 74 6f 20 41 50 49  08} Calls to API
1b190 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 64   routines that d
1b1a0 6f 20 6e 6f 74 20 72 65 74 75 72 6e 20 61 6e 20  o not return an 
1b1b0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
1b1c0 20 20 20 20 20 20 20 28 65 78 61 6d 70 6c 65 3a         (example:
1b1d0 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
1b1e0 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a  ount()]) do not.
1b1f0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68 61 6e  **          chan
1b200 67 65 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ge the error cod
1b210 65 20 6f 72 20 6d 65 73 73 61 67 65 20 72 65 74  e or message ret
1b220 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
1b230 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72       [sqlite3_er
1b240 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74  rcode()], [sqlit
1b250 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72  e3_errmsg()], or
1b260 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1b270 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  16()]..**.** {F1
1b280 32 38 30 39 7d 20 49 6e 74 65 72 66 61 63 65 73  2809} Interfaces
1b290 20 74 68 61 74 20 61 72 65 20 6e 6f 74 20 61 73   that are not as
1b2a0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
1b2b0 73 70 65 63 69 66 69 63 0a 2a 2a 20 20 20 20 20  specific.**     
1b2c0 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
1b2d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 65 78 61 6d  onnection] (exam
1b2e0 70 6c 65 73 3a 0a 2a 2a 20 20 20 20 20 20 20 20  ples:.**        
1b2f0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e    [sqlite3_mprin
1b300 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  tf()] or [sqlite
1b310 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
1b320 63 61 63 68 65 28 29 5d 0a 2a 2a 20 20 20 20 20  cache()].**     
1b330 20 20 20 20 20 64 6f 20 6e 6f 74 20 63 68 61 6e       do not chan
1b340 67 65 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  ge the values re
1b350 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20  turned by.**    
1b360 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
1b370 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69  rrcode()], [sqli
1b380 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f  te3_errmsg()], o
1b390 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
1b3a0 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  g16()]..*/.int s
1b3b0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
1b3c0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
1b3d0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1b3e0 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
1b3f0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
1b400 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1b410 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1b420 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
1b430 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
1b440 20 7b 46 31 33 30 30 30 7d 0a 2a 2a 20 4b 45 59   {F13000}.** KEY
1b450 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
1b460 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
1b470 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1b480 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
1b490 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
1b4a0 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
1b4b0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
1b4c0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
1b4d0 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
1b4e0 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
1b4f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1b500 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
1b510 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
1b520 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
1b530 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
1b540 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
1b550 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
1b560 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
1b570 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
1b580 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
1b590 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
1b5a0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1b5b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1b5c0 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
1b5d0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
1b5e0 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
1b5f0 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
1b600 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
1b610 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1b620 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
1b630 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
1b640 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
1b650 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
1b660 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
1b670 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
1b680 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
1b690 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1b6a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
1b6b0 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
1b6c0 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
1b6d0 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
1b6e0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
1b6f0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
1b700 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
1b710 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1b720 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
1b730 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
1b740 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
1b750 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
1b760 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
1b770 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1b780 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
1b790 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
1b7a0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
1b7b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b7c0 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
1b7d0 20 7b 46 31 32 37 36 30 7d 0a 2a 2a 0a 2a 2a 20   {F12760}.**.** 
1b7e0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1b7f0 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
1b800 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
1b810 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
1b820 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
1b830 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
1b840 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
1b850 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1b860 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
1b870 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1b880 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
1b890 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
1b8a0 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
1b8b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1b8c0 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
1b8d0 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
1b8e0 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
1b8f0 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
1b900 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
1b910 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
1b920 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
1b930 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
1b940 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
1b950 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69  uct.  The functi
1b960 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f  on returns the o
1b970 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20  ld limit..**.** 
1b980 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
1b990 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
1b9a0 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
1b9b0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
1b9c0 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20  * For the limit 
1b9d0 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49  category of SQLI
1b9e0 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65  TE_LIMIT_XYZ the
1b9f0 72 65 20 69 73 20 61 20 68 61 72 64 20 75 70 70  re is a hard upp
1ba00 65 72 0a 2a 2a 20 62 6f 75 6e 64 20 73 65 74 20  er.** bound set 
1ba10 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  by a compile-tim
1ba20 65 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  e C preprocessor
1ba30 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c   macro named SQL
1ba40 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20  ITE_MAX_XYZ..** 
1ba50 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
1ba60 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
1ba70 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
1ba80 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74  .).** Attempts t
1ba90 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
1baa0 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
1bab0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
1bac0 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
1bad0 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
1bae0 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e  ard upper limit.
1baf0 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20  .**.** Run time 
1bb00 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
1bb10 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
1bb20 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1bb30 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
1bb40 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
1bb50 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
1bb60 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
1bb70 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
1bb80 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
1bb90 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
1bba0 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
1bbb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
1bbc0 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 62 72  ht be a.** webbr
1bbd0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
1bbe0 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
1bbf0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
1bc00 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
1bc10 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
1bc20 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
1bc30 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
1bc40 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
1bc50 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
1bc60 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
1bc70 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
1bc80 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
1bc90 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
1bca0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
1bcb0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
1bcc0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
1bcd0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
1bce0 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
1bcf0 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
1bd00 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
1bd10 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
1bd20 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
1bd30 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
1bd40 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
1bd50 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1bd60 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
1bd70 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
1bd80 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
1bd90 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
1bda0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1bdb0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
1bdc0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
1bdd0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
1bde0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
1bdf0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1be00 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
1be10 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
1be20 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
1be30 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
1be40 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62  ental and is sub
1be50 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68 61 6e 67  ject.** to chang
1be60 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 77 69 74  e or removal wit
1be70 68 6f 75 74 20 70 72 69 6f 72 20 6e 6f 74 69 63  hout prior notic
1be80 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
1be90 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  NTS:.**.** {F127
1bea0 36 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  62} A successful
1beb0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1bec0 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20  3_limit(D,C,V)] 
1bed0 77 68 65 72 65 20 56 20 69 73 0a 2a 2a 20 20 20  where V is.**   
1bee0 20 20 20 20 20 20 20 70 6f 73 69 74 69 76 65 20         positive 
1bef0 63 68 61 6e 67 65 73 20 74 68 65 20 6c 69 6d 69  changes the limi
1bf00 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  t on the size of
1bf10 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20   construct C in 
1bf20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1bf30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1bf40 74 69 6f 6e 5d 20 44 20 74 6f 20 74 68 65 20 6c  tion] D to the l
1bf50 65 73 73 65 72 20 6f 66 20 56 20 61 6e 64 20 74  esser of V and t
1bf60 68 65 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a  he hard upper.**
1bf70 20 20 20 20 20 20 20 20 20 20 62 6f 75 6e 64 20            bound 
1bf80 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 43  on the size of C
1bf90 20 74 68 61 74 20 69 73 20 73 65 74 20 61 74 20   that is set at 
1bfa0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a  compile-time..**
1bfb0 0a 2a 2a 20 7b 46 31 32 37 36 36 7d 20 41 20 73  .** {F12766} A s
1bfc0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1bfd0 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  o [sqlite3_limit
1bfe0 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56  (D,C,V)] where V
1bff0 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
1c000 20 20 20 20 20 20 20 20 20 6c 65 61 76 65 73 20           leaves 
1c010 74 68 65 20 73 74 61 74 65 20 6f 66 20 74 68 65  the state of the
1c020 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c030 63 74 69 6f 6e 5d 20 44 20 75 6e 63 68 61 6e 67  ction] D unchang
1c040 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36  ed..**.** {F1276
1c050 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  9} A successful 
1c060 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1c070 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 72  _limit(D,C,V)] r
1c080 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
1c090 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
1c0a0 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65  the limit on the
1c0b0 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75   size of constru
1c0c0 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ct C in the.**  
1c0d0 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
1c0e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1c0f0 61 73 20 69 74 20 77 61 73 20 70 72 69 6f 72 20  as it was prior 
1c100 74 6f 20 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a  to the call..*/.
1c110 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
1c120 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
1c130 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
1c140 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c150 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
1c160 20 43 61 74 65 67 6f 72 69 65 73 20 7b 46 31 32   Categories {F12
1c170 37 39 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  790}.** KEYWORDS
1c180 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
1c190 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  y} {limit catego
1c1a0 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
1c1b0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
1c1c0 6e 65 20 76 61 72 69 6f 75 73 20 61 73 70 65 63  ne various aspec
1c1d0 74 73 20 6f 66 20 61 20 5b 64 61 74 61 62 61 73  ts of a [databas
1c1e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
1c1f0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 69 6d   that can be lim
1c200 69 74 65 64 20 69 6e 20 73 69 7a 65 20 62 79 20  ited in size by 
1c210 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1c220 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
1c230 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
1c240 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
1c250 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73  s are as follows
1c260 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  :.**.** <dl>.** 
1c270 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c280 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1c290 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1c2a0 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
1c2b0 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
1c2c0 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a  ble row.<dd>.**.
1c2d0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1c2e0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
1c2f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c300 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1c310 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1c320 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
1c330 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
1c340 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
1c350 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1c360 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1c370 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
1c380 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
1c390 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
1c3a0 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74 68 65   a SELECT or the
1c3b0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1c3c0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
1c3d0 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
1c3e0 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
1c3f0 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
1c400 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1c410 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1c420 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
1c430 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
1c440 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
1c450 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
1c460 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  pression.</dd>.*
1c470 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1c480 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
1c490 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
1c4a0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1c4b0 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
1c4c0 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
1c4d0 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
1c4e0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1c4f0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
1c500 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
1c510 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1c520 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
1c530 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
1c540 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
1c550 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1c560 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
1c570 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
1c580 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c590 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
1c5a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c5b0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1c5c0 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
1c5d0 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  unction.</dd>.**
1c5e0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1c5f0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
1c600 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c610 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1c620 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
1c630 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  es.</dd>.**.** <
1c640 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c650 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
1c660 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1c670 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
1c680 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
1c690 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
1c6a0 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f  e LIKE or.** GLO
1c6b0 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  B operators.</dd
1c6c0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1c6d0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
1c6e0 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
1c6f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1c700 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61   number of varia
1c710 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73  bles in an SQL s
1c720 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61  tatement that ca
1c730 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f  n.** be bound.</
1c740 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  dd>.** </dl>.*/.
1c750 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c760 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
1c770 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1c780 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c790 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
1c7a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c7b0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
1c7c0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
1c7d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c7e0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
1c7f0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
1c800 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1c810 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
1c820 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
1c830 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
1c840 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
1c850 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
1c860 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
1c870 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
1c880 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
1c890 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
1c8a0 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
1c8b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
1c8c0 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
1c8d0 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
1c8e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
1c8f0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
1c900 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
1c910 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
1c920 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
1c930 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a          9../*.**
1c940 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1c950 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
1c960 65 6d 65 6e 74 20 7b 46 31 33 30 31 30 7d 0a 2a  ement {F13010}.*
1c970 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
1c980 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
1c990 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
1c9a0 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
1c9b0 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
1c9c0 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
1c9d0 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
1c9e0 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
1c9f0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
1ca00 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
1ca10 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
1ca20 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
1ca30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ca40 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
1ca50 61 0a 2a 2a 20 70 72 69 6f 72 20 63 61 6c 6c 20  a.** prior call 
1ca60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1ca70 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1ca80 65 6e 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  en_v2()] or [sql
1ca90 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
1caa0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
1cab0 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
1cac0 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
1cad0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
1cae0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
1caf0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
1cb00 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
1cb10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1cb20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1cb30 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
1cb40 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
1cb50 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
1cb60 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
1cb70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1cb80 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
1cb90 2d 31 36 2e 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  -16.{END}.**.** 
1cba0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
1cbb0 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
1cbc0 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
1cbd0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
1cbe0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
1cbf0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49  ro terminator. I
1cc00 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
1cc10 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
1cc20 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
1cc30 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
1cc40 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
1cc50 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20  ql.  When nByte 
1cc60 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
1cc70 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
1cc80 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
1cc90 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
1cca0 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
1ccb0 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
1ccc0 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
1ccd0 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
1cce0 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
1ccf0 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
1cd00 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
1cd10 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
1cd20 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
1cd30 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
1cd40 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
1cd50 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
1cd60 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
1cd70 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
1cd80 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
1cd90 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
1cda0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
1cdb0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1cdc0 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
1cdd0 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
1cde0 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e  erminator bytes.
1cdf0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54  {END}.**.** *pzT
1ce00 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
1ce10 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
1ce20 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20  t byte past the 
1ce30 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  end of the.** fi
1ce40 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
1ce50 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
1ce60 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20  e routines only 
1ce70 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
1ce80 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  t.** statement i
1ce90 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
1cea0 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
1ceb0 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61  ing to what rema
1cec0 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65  ins.** uncompile
1ced0 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74  d..**.** *ppStmt
1cee0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
1cef0 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
1cf00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1cf10 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
1cf20 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
1cf30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1cf40 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69  ()].  If there i
1cf50 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
1cf60 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
1cf70 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69   NULL.  If the i
1cf80 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
1cf90 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
1cfa0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
1cfb0 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
1cfc0 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
1cfd0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
1cfe0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 55 31 33  to NULL..** {U13
1cff0 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67  018} The calling
1d000 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
1d010 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
1d020 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
1d030 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
1d040 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
1d050 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
1d060 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
1d070 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
1d080 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
1d090 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
1d0a0 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77  returned, otherw
1d0b0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1d0c0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1d0d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1d0e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1d0f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1d100 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
1d110 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
1d120 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
1d130 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
1d140 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
1d150 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
1d160 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
1d170 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1d180 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
1d190 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
1d1a0 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32  d..** In the "v2
1d1b0 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
1d1c0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
1d1d0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
1d1e0 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
1d1f0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
1d200 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
1d210 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
1d220 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
1d230 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20 63 61 75  . {END} This cau
1d240 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
1d250 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
1d260 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
1d270 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  a differently in
1d280 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a   two ways:.**.**
1d290 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
1d2a0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1d2b0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
1d2c0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
1d2d0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
1d2e0 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
1d2f0 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
1d300 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1d310 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
1d320 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
1d330 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
1d340 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
1d350 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49  run it again.  I
1d360 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73  f the schema has
1d370 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61   changed in.** a
1d380 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20   way that makes 
1d390 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f  the statement no
1d3a0 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b   longer valid, [
1d3b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d3c0 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65  will still.** re
1d3d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  turn [SQLITE_SCH
1d3e0 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b  EMA].  But unlik
1d3f0 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
1d400 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53  avior, [SQLITE_S
1d410 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77  CHEMA] is.** now
1d420 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20   a fatal error. 
1d430 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
1d440 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1d450 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d  again will not m
1d460 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  ake the.** error
1d470 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a   go away.  Note:
1d480 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   use [sqlite3_er
1d490 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20  rmsg()] to find 
1d4a0 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74  the text.** of t
1d4b0 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72  he parsing error
1d4c0 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e   that results in
1d4d0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45   an [SQLITE_SCHE
1d4e0 4d 41 5d 20 72 65 74 75 72 6e 2e 20 7b 45 4e 44  MA] return. {END
1d4f0 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  }.** </li>.**.**
1d500 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e   <li>.** When an
1d510 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
1d520 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d530 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
1d540 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
1d550 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
1d560 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
1d570 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54 68 65  ror codes].  The
1d580 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
1d590 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
1d5a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
1d5b0 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
1d5c0 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
1d5d0 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
1d5e0 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20  code.** and you 
1d5f0 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
1d600 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
1d610 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
1d620 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a  et()] in order.*
1d630 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  * to find the un
1d640 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
1d650 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
1d660 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
1d670 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
1d680 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
1d690 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
1d6a0 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
1d6b0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
1d6c0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
1d6d0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  l>.**.** INVARIA
1d6e0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  NTS:.**.** {F130
1d6f0 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
1d700 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c  _prepare(db,zSql
1d710 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  ,...)] and.**   
1d720 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1d730 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
1d740 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ql,...)] interfa
1d750 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68  ces interpret th
1d760 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65  e.**          te
1d770 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c  xt in their zSql
1d780 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54   parameter as UT
1d790 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  F-8..**.** {F130
1d7a0 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
1d7b0 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a 53  _prepare16(db,zS
1d7c0 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20  ql,...)] and.** 
1d7d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1d7e0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 64  3_prepare16_v2(d
1d7f0 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74  b,zSql,...)] int
1d800 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65  erfaces interpre
1d810 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
1d820 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20    text in their 
1d830 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61  zSql parameter a
1d840 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
1d850 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1d860 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 33  r..**.** {F13013
1d870 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61  } If the nByte a
1d880 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
1d890 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
1d8a0 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e  b,zSql,nByte,...
1d8b0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1d8c0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  nd its variants 
1d8d0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
1d8e0 6f 2c 20 74 68 65 20 53 51 4c 20 74 65 78 74 20  o, the SQL text 
1d8f0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  is.**          r
1d900 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73  ead from zSql is
1d910 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20   read up to the 
1d920 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
1d930 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  nator..**.** {F1
1d940 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e 42 79  3014} If the nBy
1d950 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  te argument to [
1d960 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d970 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65  v2(db,zSql,nByte
1d980 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
1d990 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61     and its varia
1d9a0 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  nts is non-negat
1d9b0 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d 6f 73  ive, then at mos
1d9c0 74 20 6e 42 79 74 65 73 20 62 79 74 65 73 20 6f  t nBytes bytes o
1d9d0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  f.**          SQ
1d9e0 4c 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66  L text is read f
1d9f0 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20  rom zSql..**.** 
1da00 7b 46 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c  {F13015} In [sql
1da10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1da20 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61  db,zSql,N,P,pzTa
1da30 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  il)] and its var
1da40 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  iants.**        
1da50 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e    if the zSql in
1da60 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
1da70 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
1da80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
1da90 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a            and pz
1daa0 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
1dab0 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  , then *pzTail i
1dac0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
1dad0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
1dae0 20 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61     first byte pa
1daf0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
1db00 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
1db10 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a  ement in zSql..*
1db20 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f  *          <todo
1db30 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61  >What does *pzTa
1db40 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74  il point to if t
1db50 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74  here is one stat
1db60 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  ement?</todo>.**
1db70 0a 2a 2a 20 7b 46 31 33 30 31 36 7d 20 41 20 73  .** {F13016} A s
1db80 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1db90 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1dba0 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c  re_v2(db,zSql,N,
1dbb0 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ppStmt,...)].** 
1dbc0 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20           or one 
1dbd0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  of its variants 
1dbe0 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53  writes into *ppS
1dbf0 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  tmt a pointer to
1dc00 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20   a new.**       
1dc10 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
1dc20 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69  tement] or a poi
1dc30 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 69 66 20  nter to NULL if 
1dc40 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  zSql contains.**
1dc50 20 20 20 20 20 20 20 20 20 20 6e 6f 74 68 69 6e            nothin
1dc60 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69  g other than whi
1dc70 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65  tespace or comme
1dc80 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  nts..**.** {F130
1dc90 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  19} The [sqlite3
1dca0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1dcb0 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73  nterface and its
1dcc0 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e   variants return
1dcd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
1dce0 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61  LITE_OK] or an a
1dcf0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
1dd00 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69  r code] upon fai
1dd10 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  lure..**.** {F13
1dd20 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c  021} Before [sql
1dd30 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c  ite3_prepare(db,
1dd40 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d  zSql,nByte,ppStm
1dd50 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74  t,pzTail)] or it
1dd60 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  s.**          va
1dd70 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61  riants returns a
1dd80 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c  n error (any val
1dd90 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
1dda0 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20  QLITE_OK]),.**  
1ddb0 20 20 20 20 20 20 20 20 74 68 65 79 20 66 69 72          they fir
1ddc0 73 74 20 73 65 74 20 2a 70 70 53 74 6d 74 20 74  st set *ppStmt t
1ddd0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
1dde0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
1ddf0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1de00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1de10 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1de20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1de30 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1de40 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1de50 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
1de60 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1de70 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1de80 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1de90 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1dea0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1deb0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1dec0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1ded0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1dee0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1def0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1df00 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1df10 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1df20 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1df30 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
1df40 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1df50 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1df60 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1df70 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
1df80 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1df90 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
1dfa0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1dfb0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1dfc0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1dfd0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1dfe0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1dff0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1e000 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1e010 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1e020 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
1e030 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1e040 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1e050 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1e060 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1e070 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
1e080 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1e090 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1e0a0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1e0b0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
1e0c0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1e0d0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
1e0e0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1e0f0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1e100 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1e110 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1e120 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1e130 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1e140 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1e150 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1e160 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
1e170 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1e180 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1e190 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1e1a0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1e1b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1e1c0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
1e1d0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1e1e0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1e1f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1e200 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1e210 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1e220 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
1e230 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1e240 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1e250 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1e260 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1e270 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1e280 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1e290 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1e2a0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1e2b0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
1e2c0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1e2d0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1e2e0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1e2f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45  );../*.** CAPIRE
1e300 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
1e310 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33  atement SQL {F13
1e320 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  100}.**.** This 
1e330 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1e340 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
1e350 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
1e360 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
1e370 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
1e380 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
1e390 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e3a0 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
1e3b0 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
1e3c0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
1e3d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e3e0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
1e3f0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1e400 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
1e410 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
1e420 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65  101} If the [pre
1e430 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e440 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61   passed as the a
1e450 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20  rgument to.**   
1e460 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1e470 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69  sql()] was compi
1e480 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
1e490 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e4a0 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  e_v2()] or.**   
1e4b0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1e4c0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c  prepare16_v2()],
1e4d0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   then [sqlite3_s
1e4e0 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a  ql()] returns.**
1e4f0 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e            a poin
1e500 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
1e510 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20  rminated string 
1e520 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46  containing a UTF
1e530 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20  -8 rendering.** 
1e540 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
1e550 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61  original SQL sta
1e560 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  tement..**.** {F
1e570 31 33 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70  13102} If the [p
1e580 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e590 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65  t] passed as the
1e5a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1e5b0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1e5c0 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
1e5d0 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
1e5e0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
1e5f0 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  are()] or.**    
1e600 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
1e610 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65  repare16()], the
1e620 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  n [sqlite3_sql()
1e630 5d 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ] returns a NULL
1e640 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1e650 7b 46 31 33 31 30 33 7d 20 54 68 65 20 73 74 72  {F13103} The str
1e660 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20  ing returned by 
1e670 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d  [sqlite3_sql(S)]
1e680 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
1e690 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1e6a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1e6b0 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65 74 65  ent] S is delete
1e6c0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1e6d0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a  _finalize(S)]..*
1e6e0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1e6f0 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
1e700 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
1e710 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e720 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
1e730 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20  ed Value Object 
1e740 7b 46 31 35 30 30 30 7d 0a 2a 2a 20 4b 45 59 57  {F15000}.** KEYW
1e750 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
1e760 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
1e770 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
1e780 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
1e790 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
1e7a0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
1e7b0 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
1e7c0 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
1e7d0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
1e7e0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
1e7f0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
1e800 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
1e810 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
1e820 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
1e830 2e 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20  . Values stored 
1e840 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
1e850 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
1e860 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
1e870 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
1e880 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
1e890 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
1e8a0 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
1e8b0 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
1e8c0 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
1e8d0 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
1e8e0 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
1e8f0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
1e900 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
1e910 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
1e920 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
1e930 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
1e940 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
1e950 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
1e960 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1e970 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
1e980 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
1e990 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
1e9a0 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
1e9b0 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
1e9c0 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
1e9d0 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
1e9e0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
1e9f0 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
1ea00 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
1ea10 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
1ea20 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
1ea30 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
1ea40 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e   held.  A intern
1ea50 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
1ea60 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
1ea70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1ea80 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
1ea90 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
1eaa0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
1eab0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1eac0 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
1ead0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1eae0 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
1eaf0 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
1eb00 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1eb10 45 3d 30 20 61 6e 64 20 77 69 74 68 20 5b 73 71  E=0 and with [sq
1eb20 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
1eb30 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
1eb40 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
1eb50 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
1eb60 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
1eb70 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
1eb80 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1eb90 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
1eba0 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
1ebb0 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
1ebc0 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
1ebd0 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
1ebe0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
1ebf0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
1ec00 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
1ec10 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
1ec20 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
1ec30 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72  tween between pr
1ec40 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1ec50 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1ec60 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1ec70 20 65 76 65 6e 20 69 66 20 74 68 65 79 20 61 72   even if they ar
1ec80 65 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 65  e single threade
1ec90 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1eca0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1ecb0 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
1ecc0 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
1ecd0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
1ece0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
1ecf0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1ed00 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1ed10 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
1ed20 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
1ed30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
1ed40 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
1ed50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
1ed60 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
1ed70 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
1ed80 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1ed90 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
1eda0 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
1edb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
1edc0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
1edd0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
1ede0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
1edf0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
1ee00 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
1ee10 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
1ee20 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
1ee30 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
1ee40 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1ee50 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
1ee60 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
1ee70 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
1ee80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ee90 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
1eea0 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b  Context Object {
1eeb0 46 31 36 30 30 31 7d 0a 2a 2a 0a 2a 2a 20 54 68  F16001}.**.** Th
1eec0 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
1eed0 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
1eee0 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
1eef0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
1ef00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
1ef10 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65  bject.  A pointe
1ef20 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
1ef30 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
1ef40 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
1ef50 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
1ef60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1ef70 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1ef80 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
1ef90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
1efa0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
1efb0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
1efc0 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
1efd0 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
1efe0 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
1eff0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
1f000 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
1f010 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1f020 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
1f030 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
1f040 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
1f050 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
1f060 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
1f070 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
1f080 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
1f090 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
1f0a0 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
1f0b0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1f0c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
1f0d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
1f0e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
1f0f0 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
1f100 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
1f110 65 6e 74 73 20 7b 46 31 33 35 30 30 7d 0a 2a 2a  ents {F13500}.**
1f120 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
1f130 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
1f140 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
1f150 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
1f160 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
1f170 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
1f180 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
1f190 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53  }.**.** In the S
1f1a0 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74  QL strings input
1f1b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
1f1c0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
1f1d0 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
1f1e0 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
1f1f0 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 70 61  replaced by a pa
1f200 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f  rameter in one o
1f210 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a  f these forms:.*
1f220 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
1f230 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
1f240 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
1f250 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
1f260 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
1f270 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
1f280 68 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72  he parameter for
1f290 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e  ms shown above N
1f2a0 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  NN is an integer
1f2b0 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
1f2c0 20 56 56 56 20 69 73 20 61 6e 20 61 6c 70 68 61   VVV is an alpha
1f2d0 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74  -numeric paramet
1f2e0 65 72 20 6e 61 6d 65 2e 20 54 68 65 20 76 61 6c  er name. The val
1f2f0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
1f300 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
1f310 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
1f320 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
1f330 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
1f340 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
1f350 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
1f360 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1f370 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
1f380 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  re..**.** The fi
1f390 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1f3a0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1f3b0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
1f3c0 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
1f3d0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1f3e0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
1f3f0 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
1f400 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1f410 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
1f420 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
1f430 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1f440 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
1f450 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
1f460 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
1f470 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73  ..** The leftmos
1f480 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
1f490 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
1f4a0 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d  1.  When the sam
1f4b0 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
1f4c0 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
1f4d0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
1f4e0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
1f4f0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
1f500 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
1f510 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
1f520 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
1f530 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20  e..** The index 
1f540 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
1f550 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
1f560 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
1f570 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1f580 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1f590 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
1f5a0 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a  d.  The index.**
1f5b0 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
1f5c0 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
1f5d0 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54  lue of NNN..** T
1f5e0 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
1f5f0 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
1f600 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  nd the compile-t
1f610 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ime.** parameter
1f620 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49   SQLITE_MAX_VARI
1f630 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65 66  ABLE_NUMBER (def
1f640 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
1f650 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
1f660 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
1f670 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
1f680 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
1f690 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  ..**.** In those
1f6a0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
1f6b0 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
1f6c0 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
1f6d0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
1f6e0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
1f6f0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
1f700 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
1f710 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
1f720 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
1f730 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
1f740 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
1f750 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1f760 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72  ..** If the four
1f770 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
1f780 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65  negative, the le
1f790 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
1f7a0 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
1f7b0 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
1f7c0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
1f7d0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
1f7e0 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72  .** The fifth ar
1f7f0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1f800 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
1f810 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1f820 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
1f830 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
1f840 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
1f850 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
1f860 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
1f870 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
1f880 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
1f890 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66 20  hed with it. If 
1f8a0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
1f8b0 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
1f8c0 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
1f8d0 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
1f8e0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
1f8f0 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
1f900 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
1f910 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
1f920 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
1f930 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
1f940 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  eed..** If the f
1f950 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
1f960 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
1f970 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
1f980 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
1f990 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
1f9a0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
1f9b0 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
1f9c0 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
1f9d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1f9e0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1f9f0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
1fa00 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
1fa10 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
1fa20 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
1fa30 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
1fa40 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
1fa50 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62  oes.  A zeroblob
1fa60 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
1fa70 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
1fa80 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
1fa90 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
1faa0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
1fab0 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
1fac0 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
1fad0 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
1fae0 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
1faf0 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
1fb00 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
1fb10 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
1fb20 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1fb30 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
1fb40 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
1fb50 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
1fb60 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c  * A negative val
1fb70 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
1fb80 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
1fb90 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
1fba0 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  B..**.** The sql
1fbb0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1fbc0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
1fbd0 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b  alled after.** [
1fbe0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1fbf0 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76  v2()] (and its v
1fc00 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c  ariants) or [sql
1fc10 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e  ite3_reset()] an
1fc20 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c  d.** before [sql
1fc30 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1fc40 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f   Bindings are no
1fc50 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
1fc60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1fc70 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55  )] routine..** U
1fc80 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
1fc90 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
1fca0 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
1fcb0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1fcc0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1fcd0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
1fce0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
1fcf0 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f  f.** anything go
1fd00 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49  es wrong.  [SQLI
1fd10 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
1fd20 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
1fd30 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
1fd40 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
1fd50 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
1fd60 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
1fd70 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
1fd80 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
1fd90 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  E] might be retu
1fda0 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f  rned if these ro
1fdb0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
1fdc0 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61  d on a.** virtua
1fdd0 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69  l machine that i
1fde0 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74  s the wrong stat
1fdf0 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61  e or which has a
1fe00 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61  lready been fina
1fe10 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74  lized..** Detect
1fe20 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73  ion of misuse is
1fe30 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70   unreliable.  Ap
1fe40 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
1fe50 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20  d not depend.** 
1fe60 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  on SQLITE_MISUSE
1fe70 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54   returns.  SQLIT
1fe80 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65  E_MISUSE is inte
1fe90 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  nded to indicate
1fea0 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72   a.** a logic er
1feb0 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69  ror in the appli
1fec0 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20  cation.  Future 
1fed0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1fee0 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69  te might.** pani
1fef0 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 65  c rather than re
1ff00 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
1ff10 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  SE..**.** See al
1ff20 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1ff30 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1ff40 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
1ff50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1ff60 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
1ff70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1ff80 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1ff90 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1ffa0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 36 7d  :.**.** {F13506}
1ffb0 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d   The [SQL statem
1ffc0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65  ent compiler] re
1ffd0 63 6f 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 20  cognizes tokens 
1ffe0 6f 66 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a 20  of the forms.** 
1fff0 20 20 20 20 20 20 20 20 20 22 3f 22 2c 20 22 3f           "?", "?
20000 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20 22 3a  NNN", "$VVV", ":
20010 56 56 56 22 2c 20 61 6e 64 20 22 40 56 56 56 22  VVV", and "@VVV"
20020 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65   as SQL paramete
20030 72 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rs,.**          
20040 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79  where NNN is any
20050 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65   sequence of one
20060 20 6f 72 20 6d 6f 72 65 20 64 69 67 69 74 73 0a   or more digits.
20070 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
20080 77 68 65 72 65 20 56 56 56 20 69 73 20 61 6e 79  where VVV is any
20090 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65   sequence of one
200a0 20 6f 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e 75   or more alphanu
200b0 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20  meric.**        
200c0 20 20 63 68 61 72 61 63 74 65 72 73 20 6f 72 20    characters or 
200d0 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  "::" optionally 
200e0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 73 74  followed by a st
200f0 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 0a  ring containing.
20100 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 73  **          no s
20110 70 61 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 69  paces and contai
20120 6e 65 64 20 77 69 74 68 69 6e 20 70 61 72 65 6e  ned within paren
20130 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  theses..**.** {F
20140 31 33 35 30 39 7d 20 54 68 65 20 69 6e 69 74 69  13509} The initi
20150 61 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53  al value of an S
20160 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
20170 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  NULL..**.** {F13
20180 35 31 32 7d 20 54 68 65 20 69 6e 64 65 78 20 6f  512} The index o
20190 66 20 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 72  f an "?" SQL par
201a0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6c 61  ameter is one la
201b0 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a  rger than the.**
201c0 20 20 20 20 20 20 20 20 20 20 6c 61 72 67 65 73            larges
201d0 74 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70  t index of SQL p
201e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
201f0 6c 65 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a  left, or 1 if.**
20200 20 20 20 20 20 20 20 20 20 20 74 68 65 20 22 3f            the "?
20210 22 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73  " is the leftmos
20220 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 2e  t SQL parameter.
20230 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 35 7d 20  .**.** {F13515} 
20240 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  The index of an 
20250 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d  "?NNN" SQL param
20260 65 74 65 72 20 69 73 20 74 68 65 20 69 6e 74 65  eter is the inte
20270 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  ger NNN..**.** {
20280 46 31 33 35 31 38 7d 20 54 68 65 20 69 6e 64 65  F13518} The inde
20290 78 20 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c 20  x of an ":VVV", 
202a0 22 24 56 56 56 22 2c 20 6f 72 20 22 40 56 56 56  "$VVV", or "@VVV
202b0 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  " SQL parameter 
202c0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  is.**          t
202d0 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 69  he same as the i
202e0 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74  ndex of leftmost
202f0 20 6f 63 63 75 72 72 65 6e 63 65 73 20 6f 66 20   occurrences of 
20300 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
20310 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c 20       parameter, 
20320 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e  or one more than
20330 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64   the largest ind
20340 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20  ex over all.**  
20350 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
20360 72 73 20 74 6f 20 74 68 65 20 6c 65 66 74 20 69  rs to the left i
20370 66 20 74 68 69 73 20 69 73 20 74 68 65 20 66 69  f this is the fi
20380 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a  rst occurrence.*
20390 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
203a0 69 73 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72  is parameter, or
203b0 20 31 20 69 66 20 74 68 69 73 20 69 73 20 74 68   1 if this is th
203c0 65 20 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 6d  e leftmost param
203d0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  eter..**.** {F13
203e0 35 32 31 7d 20 54 68 65 20 5b 53 51 4c 20 73 74  521} The [SQL st
203f0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
20400 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  ] fails with an 
20410 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a 2a  [SQLITE_RANGE].*
20420 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72  *          error
20430 20 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f 66   if the index of
20440 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
20450 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31  r is less than 1
20460 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
20470 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
20480 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53 51   compile-time SQ
20490 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c  LITE_MAX_VARIABL
204a0 45 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20 20  E_NUMBER.**     
204b0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a       parameter..
204c0 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 34 7d 20 43  **.** {F13524} C
204d0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
204e0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c  _bind_text | sql
204f0 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c  ite3_bind(S,N,V,
20500 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
20510 20 20 61 73 73 6f 63 69 61 74 65 20 74 68 65 20    associate the 
20520 76 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c 6c  value V with all
20530 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
20540 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20  having an.**    
20550 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20 4e        index of N
20560 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
20570 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
20580 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 37 7d 20 43  **.** {F13527} C
20590 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
205a0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c  _bind_text | sql
205b0 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e  ite3_bind(S,N,..
205c0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
205d0 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 63  override prior c
205e0 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73 61  alls with the sa
205f0 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20 61  me values of S a
20600 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  nd N..**.** {F13
20610 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 73  530} Bindings es
20620 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73 71  tablished by [sq
20630 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
20640 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53  | sqlite3_bind(S
20650 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
20660 20 20 20 70 65 72 73 69 73 74 20 61 63 72 6f 73     persist acros
20670 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  s calls to [sqli
20680 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a  te3_reset(S)]..*
20690 2a 0a 2a 2a 20 7b 46 31 33 35 33 33 7d 20 49 6e  *.** {F13533} In
206a0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
206b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e  e3_bind_blob(S,N
206c0 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,L,D)],.**    
206d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
206e0 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
206f0 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
20700 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
20710 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
20720 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e  L,D)] SQLite bin
20730 64 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a  ds the first L.*
20740 2a 20 20 20 20 20 20 20 20 20 20 62 79 74 65 73  *          bytes
20750 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
20760 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
20770 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a  o by V, when L.*
20780 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f  *          is no
20790 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
207a0 2a 20 7b 46 31 33 35 33 36 7d 20 49 6e 20 63 61  * {F13536} In ca
207b0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
207c0 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
207d0 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  L,D)] or.**     
207e0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
207f0 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
20800 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e  L,D)] SQLite bin
20810 64 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a 2a  ds characters.**
20820 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 56            from V
20830 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
20840 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
20850 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61  r when L is nega
20860 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  tive..**.** {F13
20870 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  539} In calls to
20880 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
20890 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  lob(S,N,V,L,D)],
208a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
208b0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
208c0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a  S,N,V,L,D)], or.
208d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
208e0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
208f0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65  (S,N,V,L,D)] whe
20900 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63 69  n D is the speci
20910 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  al.**          c
20920 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f  onstant [SQLITE_
20930 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20  STATIC], SQLite 
20940 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
20950 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20   value V.**     
20960 20 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e 20       is held in 
20970 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 64  static unmanaged
20980 20 73 70 61 63 65 20 74 68 61 74 20 77 69 6c 6c   space that will
20990 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20   not change.**  
209a0 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 74          during t
209b0 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74  he lifetime of t
209c0 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a  he binding..**.*
209d0 2a 20 7b 46 31 33 35 34 32 7d 20 49 6e 20 63 61  * {F13542} In ca
209e0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
209f0 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
20a00 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
20a10 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
20a20 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
20a30 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
20a40 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
20a50 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
20a60 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65  )] when D is the
20a70 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20   special.**     
20a80 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53       constant [S
20a90 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
20aa0 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d 61  , the routine ma
20ab0 6b 65 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  kes a.**        
20ac0 20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f    private copy o
20ad0 66 20 74 68 65 20 76 61 6c 75 65 20 56 20 62 65  f the value V be
20ae0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
20af0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 35 7d 20  .**.** {F13545} 
20b00 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
20b10 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53  ite3_bind_blob(S
20b20 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20  ,N,V,L,D)],.**  
20b30 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
20b40 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
20b50 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,L,D)], or.**   
20b60 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
20b70 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c  bind_text16(S,N,
20b80 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69  V,L,D)] when D i
20b90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
20ba0 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 75 6e  *          a fun
20bb0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e  ction, SQLite in
20bc0 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63 74  vokes that funct
20bd0 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 74  ion to destroy t
20be0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  he.**          v
20bf0 61 6c 75 65 20 56 20 61 66 74 65 72 20 69 74 20  alue V after it 
20c00 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
20c10 6e 67 20 74 68 65 20 76 61 6c 75 65 20 56 2e 0a  ng the value V..
20c20 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 38 7d 20 49  **.** {F13548} I
20c30 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
20c40 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
20c50 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20  b(S,N,V,L)] the 
20c60 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20  value bound.**  
20c70 20 20 20 20 20 20 20 20 69 73 20 61 20 42 4c 4f          is a BLO
20c80 42 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f 72  B of L bytes, or
20c90 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
20ca0 4c 4f 42 20 69 66 20 4c 20 69 73 20 6e 65 67 61  LOB if L is nega
20cb0 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  tive..**.** {F13
20cc0 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  551} In calls to
20cd0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
20ce0 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65  alue(S,N,V)] the
20cf0 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a   V argument may.
20d00 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 20 65  **          be e
20d10 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74  ither a [protect
20d20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
20d30 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a  ] object or an.*
20d40 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70 72  *          [unpr
20d50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20d60 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  value] object..*
20d70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
20d80 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
20d90 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
20da0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
20db0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
20dc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
20dd0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
20de0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
20df0 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
20e00 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
20e10 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
20e20 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
20e30 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
20e40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
20e50 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
20e60 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20e70 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
20e80 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
20e90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
20ea0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
20eb0 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
20ec0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
20ed0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
20ee0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
20ef0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
20f00 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
20f10 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
20f20 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
20f30 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
20f40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
20f50 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
20f60 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
20f70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
20f80 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
20f90 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
20fa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20fb0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
20fc0 50 61 72 61 6d 65 74 65 72 73 20 7b 46 31 33 36  Parameters {F136
20fd0 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00}.**.** This r
20fe0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
20ff0 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
21000 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
21010 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
21020 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
21030 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
21040 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
21050 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
21060 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
21070 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
21080 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
21090 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
210a0 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
210b0 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
210c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
210d0 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
210e0 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
210f0 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
21100 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
21110 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
21120 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
21130 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
21140 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
21150 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
21160 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
21170 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
21180 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
21190 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
211a0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
211b0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
211c0 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a   ?NNN are used,.
211d0 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
211e0 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
211f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
21200 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
21210 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
21220 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
21230 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
21240 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
21250 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
21260 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
21270 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
21280 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36  NTS:.**.** {F136
21290 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
212a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
212b0 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66  count(S)] interf
212c0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
212d0 20 20 20 20 20 20 20 20 74 68 65 20 6c 61 72 67          the larg
212e0 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c  est index of all
212f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
21300 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
21310 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
21320 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20  tement] S, or 0 
21330 69 66 20 53 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  if S contains no
21340 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2e   SQL parameters.
21350 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
21360 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
21370 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
21380 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
21390 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
213a0 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b  Host Parameter {
213b0 46 31 33 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13620}.**.** Th
213c0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
213d0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
213e0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
213f0 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72  n-th.** [SQL par
21400 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 72  ameter] in a [pr
21410 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21420 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ]..** SQL parame
21430 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
21440 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
21450 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
21460 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
21470 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
21480 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
21490 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
214a0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
214b0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
214c0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
214d0 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
214e0 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
214f0 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
21500 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
21510 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61   the name..** Pa
21520 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
21530 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
21540 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
21550 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
21560 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73  e.** and are als
21570 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  o referred to as
21580 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
21590 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54  meters"..**.** T
215a0 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
215b0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
215c0 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
215d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76  ..**.** If the v
215e0 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66  alue n is out of
215f0 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
21600 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   n-th parameter 
21610 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
21620 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
21630 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75  urned.  The retu
21640 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
21650 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
21660 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
21670 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
21680 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
21690 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
216a0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
216b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
216c0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
216d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
216e0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
216f0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
21700 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
21710 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
21720 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21730 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
21740 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
21750 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
21760 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
21770 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
21780 7b 46 31 33 36 32 31 7d 20 54 68 65 20 5b 73 71  {F13621} The [sq
21790 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
217a0 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  eter_name(S,N)] 
217b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
217c0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  s.**          a 
217d0 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
217e0 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  of the name of t
217f0 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
21800 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   in.**          
21810 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
21820 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e  atement] S havin
21830 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a  g index N, or.**
21840 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69            NULL i
21850 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51  f there is no SQ
21860 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68  L parameter with
21870 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74   index N or if t
21880 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  he.**          p
21890 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e  arameter with in
218a0 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e  dex N is an anon
218b0 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20  ymous parameter 
218c0 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  "?"..*/.const ch
218d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
218e0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
218f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
21900 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
21910 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
21920 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
21930 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 46 31  A Given Name {F1
21940 33 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75  3640}.**.** Retu
21950 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
21960 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
21970 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
21980 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76    The.** index v
21990 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
219a0 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
219b0 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
219c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
219d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
219e0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
219f0 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69  )].  A zero.** i
21a00 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
21a10 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
21a20 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54  ter is found.  T
21a30 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
21a40 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
21a50 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
21a60 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
21a70 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
21a80 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
21a90 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
21aa0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
21ab0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
21ac0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
21ad0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
21ae0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
21af0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
21b00 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
21b10 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
21b20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
21b30 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
21b40 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
21b50 2a 2a 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20 54  **.** {F13641} T
21b60 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
21b70 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
21b80 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
21b90 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
21ba0 20 20 20 20 20 74 68 65 20 69 6e 64 65 78 20 6f       the index o
21bb0 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  f SQL parameter 
21bc0 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
21bd0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20   statement].**  
21be0 20 20 20 20 20 20 20 20 53 20 77 68 6f 73 65 20          S whose 
21bf0 6e 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68 65  name matches the
21c00 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c   UTF-8 string N,
21c10 20 6f 72 20 30 20 69 66 20 74 68 65 72 65 20 69   or 0 if there i
21c20 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f  s.**          no
21c30 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73   match..*/.int s
21c40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21c50 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
21c60 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
21c70 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
21c80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21c90 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
21ca0 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
21cb0 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 36   Statement {F136
21cc0 36 30 7d 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61  60}.**.** Contra
21cd0 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
21ce0 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
21cf0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
21d00 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
21d10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
21d20 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
21d30 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
21d40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
21d50 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69  * Use this routi
21d60 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
21d70 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
21d80 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49  to NULL..**.** I
21d90 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
21da0 20 7b 46 31 33 36 36 31 7d 20 54 68 65 20 5b 73   {F13661} The [s
21db0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
21dc0 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66  dings(S)] interf
21dd0 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c 20 53  ace resets all S
21de0 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  QL.**          p
21df0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
21e00 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  s in the [prepar
21e10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
21e20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  back to NULL..*/
21e30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
21e40 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
21e50 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
21e60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
21e70 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
21e80 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
21e90 46 31 33 37 31 30 7d 0a 2a 2a 0a 2a 2a 20 52 65  F13710}.**.** Re
21ea0 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
21eb0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
21ec0 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
21ed0 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
21ee0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21ef0 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69  ent]. This routi
21f00 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
21f10 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
21f20 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
21f30 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
21f40 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
21f50 70 6c 65 20 61 6e 20 55 50 44 41 54 45 29 2e 0a  ple an UPDATE)..
21f60 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
21f70 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 31 31 7d  :.**.** {F13711}
21f80 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
21f90 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69  lumn_count(S)] i
21fa0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
21fb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
21fc0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d  *          colum
21fd0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
21fe0 20 73 65 74 20 67 65 6e 65 72 61 74 65 64 20 62   set generated b
21ff0 79 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  y the [prepared 
22000 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a  statement] S,.**
22010 20 20 20 20 20 20 20 20 20 20 6f 72 20 30 20 69            or 0 i
22020 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e  f S does not gen
22030 65 72 61 74 65 20 61 20 72 65 73 75 6c 74 20 73  erate a result s
22040 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
22050 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
22060 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
22070 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
22080 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
22090 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
220a0 53 65 74 20 7b 46 31 33 37 32 30 7d 0a 2a 2a 0a  Set {F13720}.**.
220b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
220c0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
220d0 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
220e0 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
220f0 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
22100 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45  lt set of a SELE
22110 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  CT statement.  T
22120 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
22130 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
22140 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
22150 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
22160 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
22170 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
22180 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22190 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
221a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
221b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
221c0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
221d0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
221e0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
221f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22200 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
22210 6d 65 6e 74 73 20 74 68 65 20 53 45 4c 45 43 54  ments the SELECT
22220 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20   statement. The 
22230 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
22240 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
22250 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c  n number.  The l
22260 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
22270 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
22280 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
22290 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
222a0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
222b0 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
222c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
222d0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
222e0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
222f0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
22300 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
22310 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
22320 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
22330 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
22340 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
22350 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  olumn..**.** If 
22360 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
22370 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
22380 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
22390 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
223a0 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
223b0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
223c0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
223d0 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
223e0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
223f0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
22400 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** The name of a
22410 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
22420 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
22430 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
22440 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
22450 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
22460 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
22470 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
22480 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
22490 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
224a0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
224b0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
224c0 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
224d0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
224e0 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
224f0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
22500 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 31 7d 20  .**.** {F13721} 
22510 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
22520 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  ocation of the [
22530 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
22540 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20  ame(S,N)].**    
22550 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
22560 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65  returns the name
22570 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   of the Nth colu
22580 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 0a 2a  mn (where 0 is.*
22590 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c  *          the l
225a0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20  eftmost column) 
225b0 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74 20 73  for the result s
225c0 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  et of the.**    
225d0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
225e0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20  statement] S as 
225f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
22600 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  d UTF-8 string..
22610 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 33 7d 20 41  **.** {F13723} A
22620 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
22630 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  cation of the [s
22640 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
22650 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20  me16(S,N)].**   
22660 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
22670 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d   returns the nam
22680 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  e of the Nth col
22690 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 0a  umn (where 0 is.
226a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
226b0 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29  leftmost column)
226c0 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74 20   for the result 
226d0 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  set of the.**   
226e0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
226f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73   statement] S as
22700 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
22710 65 64 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ed UTF-16 string
22720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
22730 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
22740 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  order..**.** {F1
22750 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  3724} The [sqlit
22760 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
22770 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
22780 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a  olumn_name16()].
22790 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
227a0 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 20  rfaces return a 
227b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
227c0 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c 65 20  they are unable 
227d0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  to.**          a
227e0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
227f0 6f 20 68 6f 6c 64 20 74 68 65 69 72 20 6e 6f 72  o hold their nor
22800 6d 61 6c 20 72 65 74 75 72 6e 20 73 74 72 69 6e  mal return strin
22810 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32  gs..**.** {F1372
22820 35 7d 20 49 66 20 74 68 65 20 4e 20 70 61 72 61  5} If the N para
22830 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
22840 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c  3_column_name(S,
22850 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  N)] or.**       
22860 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
22870 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  mn_name16(S,N)] 
22880 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
22890 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   then the.**    
228a0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
228b0 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70   return a NULL p
228c0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ointer..**.** {F
228d0 31 33 37 32 36 7d 20 54 68 65 20 73 74 72 69 6e  13726} The strin
228e0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  gs returned by [
228f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
22900 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a  ame(S,N)] and.**
22910 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
22920 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
22930 28 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c 69 64  (S,N)] are valid
22940 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a   until the next.
22950 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
22960 20 74 6f 20 65 69 74 68 65 72 20 72 6f 75 74 69   to either routi
22970 6e 65 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ne with the same
22980 20 53 20 61 6e 64 20 4e 20 70 61 72 61 6d 65 74   S and N paramet
22990 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
229a0 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
229b0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69  3_finalize(S)] i
229c0 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  s called..**.** 
229d0 7b 46 31 33 37 32 37 7d 20 57 68 65 6e 20 61 20  {F13727} When a 
229e0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
229f0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
22a00 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a  ement contains.*
22a10 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 41 53  *          an AS
22a20 20 63 6c 61 75 73 65 2c 20 74 68 65 20 6e 61 6d   clause, the nam
22a30 65 20 6f 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e  e of that column
22a40 20 69 73 20 74 68 65 20 69 64 65 6e 74 69 66 69   is the identifi
22a50 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
22a60 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66 20 74  o the right of t
22a70 68 65 20 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a  he AS keyword..*
22a80 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
22a90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
22aa0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
22ab0 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76   int N);.const v
22ac0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
22ad0 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
22ae0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
22af0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22b00 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
22b10 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
22b20 75 6c 74 20 7b 46 31 33 37 34 30 7d 0a 2a 2a 0a  ult {F13740}.**.
22b30 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
22b40 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
22b50 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77  s to determine w
22b60 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68  hat column of wh
22b70 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77  at.** table in w
22b80 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61 20  hich database a 
22b90 72 65 73 75 6c 74 20 6f 66 20 61 20 53 45 4c 45  result of a SELE
22ba0 43 54 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  CT statement com
22bb0 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20  es from..** The 
22bc0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
22bd0 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
22be0 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
22bf0 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
22c00 74 68 65 72 20 61 20 55 54 46 38 20 6f 72 20 55  ther a UTF8 or U
22c10 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68  TF16 string.  Th
22c20 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
22c30 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
22c40 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
22c50 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
22c60 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
22c70 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
22c80 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
22c90 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
22ca0 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
22cb0 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  e..** The return
22cc0 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
22cd0 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
22ce0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22cf0 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
22d00 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
22d10 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
22d20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
22d30 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
22d40 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
22d50 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
22d60 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
22d70 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
22d80 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
22d90 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
22da0 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
22db0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
22dc0 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
22dd0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
22de0 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c  ment to the foll
22df0 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61  owing calls is a
22e00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22e10 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20  ment]..** These 
22e20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
22e30 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
22e40 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  ut the Nth colum
22e50 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
22e60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
22e70 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
22e80 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
22e90 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49  rgument..**.** I
22ea0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
22eb0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
22ec0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
22ed0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
22ee0 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
22ef0 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
22f00 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
22f10 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
22f20 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
22f30 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
22f40 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
22f50 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
22f60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
22f70 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
22f80 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79   Otherwise, they
22f90 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
22fa0 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
22fb0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
22fc0 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74  .** and column t
22fd0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
22fe0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
22ff0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
23000 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74  * As with all ot
23010 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
23020 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64   those postfixed
23030 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
23040 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
23050 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65  ded strings, the
23060 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
23070 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b   return UTF-8. {
23080 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  END}.**.** These
23090 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
230a0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
230b0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
230c0 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
230d0 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
230e0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70  OLUMN_METADATA p
230f0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
23100 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  ol defined..**.*
23110 2a 20 7b 55 31 33 37 35 31 7d 0a 2a 2a 20 49 66  * {U13751}.** If
23120 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
23130 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
23140 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
23150 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
23160 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
23170 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
23180 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
23190 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
231a0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
231b0 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
231c0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
231d0 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 31 7d 20 54  **.** {F13741} T
231e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
231f0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
23200 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
23210 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
23220 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
23230 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
23240 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
23250 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20  e database from 
23260 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20  which the.**    
23270 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74        Nth result
23280 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b   column of the [
23290 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
232a0 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74  nt] S is extract
232b0 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed,.**          
232c0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
232d0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
232e0 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72  s a general expr
232f0 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ession.**       
23300 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20     or if unable 
23310 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
23320 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20  ry to store the 
23330 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  name..**.** {F13
23340 37 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  742} The [sqlite
23350 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
23360 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  e_name16(S,N)] i
23370 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23380 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
23390 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
233a0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
233b0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
233c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
233d0 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20  abase.**        
233e0 20 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65    from which the
233f0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
23400 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61  mn of the [prepa
23410 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
23420 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
23430 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
23440 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
23450 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67  lumn of S is a g
23460 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
23470 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
23480 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
23490 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
234a0 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
234b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 33 7d 20  .**.** {F13743} 
234c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
234d0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53  umn_table_name(S
234e0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
234f0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
23500 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
23510 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
23520 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
23530 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68  table from which
23540 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
23550 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
23560 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61  mn of the [prepa
23570 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
23580 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a   is extracted,.*
23590 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55  *          or NU
235a0 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
235b0 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67  lumn of S is a g
235c0 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
235d0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
235e0 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
235f0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
23600 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
23610 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 34 7d 20  .**.** {F13744} 
23620 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
23630 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
23640 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
23650 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
23660 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
23670 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
23680 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65  te order zero-te
23690 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
236a0 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20   the table.**   
236b0 20 20 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63         from whic
236c0 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  h the Nth result
236d0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b   column of the [
236e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
236f0 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20  nt] S is.**     
23700 20 20 20 20 20 65 78 74 72 61 63 74 65 64 2c 20       extracted, 
23710 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
23720 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
23730 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72  s a general expr
23740 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ession.**       
23750 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20     or if unable 
23760 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
23770 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20  ry to store the 
23780 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  name..**.** {F13
23790 37 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  745} The [sqlite
237a0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
237b0 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
237c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
237d0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
237e0 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  the UTF-8 zero-t
237f0 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
23800 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
23810 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  mn from which th
23820 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
23830 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
23840 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  of the [prepared
23850 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
23860 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20   extracted,.**  
23870 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20          or NULL 
23880 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
23890 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65  n of S is a gene
238a0 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  ral expression.*
238b0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
238c0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
238d0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74  ate memory to st
238e0 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
238f0 0a 2a 2a 20 7b 46 31 33 37 34 36 7d 20 54 68 65  .** {F13746} The
23900 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
23910 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53  _origin_name16(S
23920 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
23930 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
23940 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
23950 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
23960 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d   order zero-term
23970 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
23980 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  he table.**     
23990 20 20 20 20 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d       column from
239a0 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72   which the Nth r
239b0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
239c0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
239d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
239e0 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63  ent] S is extrac
239f0 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
23a00 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a  the Nth column.*
23a10 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 53 20  *          of S 
23a20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70  is a general exp
23a30 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e  ression or if un
23a40 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
23a50 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20   memory.**      
23a60 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65      to store the
23a70 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   name..**.** {F1
23a80 33 37 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e  3748} The return
23a90 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20   values from.** 
23aa0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
23ab0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
23ac0 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
23ad0 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
23ae0 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ces].**         
23af0 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 74   are valid for t
23b00 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74  he lifetime of t
23b10 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23b20 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20  tement].**      
23b30 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65      or until the
23b40 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 63 68 61   encoding is cha
23b50 6e 67 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20  nged by another 
23b60 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20  metadata.**     
23b70 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63       interface c
23b80 61 6c 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65  all for the same
23b90 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
23ba0 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  ent and column..
23bb0 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
23bc0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31  S:.**.** {U13751
23bd0 7d 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  } If two or more
23be0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
23bf0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20  e or more.**    
23c00 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
23c10 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
23c20 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
23c30 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
23c40 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f  ].**          fo
23c50 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
23c60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23c70 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
23c80 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74  n.**          at
23c90 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
23ca0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
23cb0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
23cc0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
23cd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
23ce0 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
23cf0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
23d00 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
23d10 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
23d20 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
23d30 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
23d40 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
23d50 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
23d60 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
23d70 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
23d80 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
23d90 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
23da0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
23db0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
23dc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
23dd0 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
23de0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
23df0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
23e00 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
23e10 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
23e20 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
23e30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
23e40 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
23e50 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
23e60 20 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a 2a 20   {F13760}.**.** 
23e70 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
23e80 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
23e90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
23ea0 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
23eb0 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54 20  ent is a SELECT 
23ec0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
23ed0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
23ee0 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
23ef0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
23f00 61 74 20 53 45 4c 45 43 54 20 69 73 20 61 20 74  at SELECT is a t
23f10 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
23f20 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
23f30 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
23f40 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
23f50 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
23f60 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
23f70 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68  returned.  If th
23f80 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
23f90 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
23fa0 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
23fb0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
23fc0 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
23fd0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
23fe0 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
23ff0 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
24000 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
24010 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72   {END}.**.** For
24020 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
24030 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
24040 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
24050 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
24060 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
24070 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
24080 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
24090 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
240a0 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
240b0 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
240c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
240d0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
240e0 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
240f0 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
24100 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
24110 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
24120 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
24130 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
24140 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a  column (i==0)..*
24150 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
24160 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
24170 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75  e typing.  So ju
24180 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
24190 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
241a0 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
241b0 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
241c0 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
241d0 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
241e0 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
241f0 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
24200 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
24210 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
24220 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
24230 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
24240 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
24250 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73  .  Type.** is as
24260 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
24270 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
24280 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
24290 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
242a0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
242b0 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  alues..**.** INV
242c0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
242d0 46 31 33 37 36 31 7d 20 20 41 20 73 75 63 63 65  F13761}  A succe
242e0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
242f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
24300 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 72 65 74  cltype(S,N)] ret
24310 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
24320 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
24330 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
24340 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
24350 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79 70  declared datatyp
24360 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  e.**           o
24370 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
24380 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 20  mn that appears 
24390 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  as the Nth colum
243a0 6e 20 28 6e 75 6d 62 65 72 65 64 0a 2a 2a 20 20  n (numbered.**  
243b0 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 30 29           from 0)
243c0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
243d0 65 74 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  et to the [prepa
243e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
243f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 32 7d  ..**.** {F13762}
24400 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63    A successful c
24410 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
24420 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
24430 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20  6(S,N)].**      
24440 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 7a       returns a z
24450 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
24460 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
24470 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67 0a 2a  e order string.*
24480 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  *           cont
24490 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61  aining the decla
244a0 72 65 64 20 64 61 74 61 74 79 70 65 20 6f 66 20  red datatype of 
244b0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
244c0 20 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a 2a   that appears.**
244d0 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68             as th
244e0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75  e Nth column (nu
244f0 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f  mbered from 0) o
24500 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
24510 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
24520 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
24530 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
24540 2a 2a 20 7b 46 31 33 37 36 33 7d 20 20 49 66 20  ** {F13763}  If 
24550 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 30  N is less than 0
24560 20 6f 72 20 4e 20 69 73 20 67 72 65 61 74 65 72   or N is greater
24570 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
24580 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  o.**           t
24590 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
245a0 75 6d 6e 73 20 69 6e 20 74 68 65 20 5b 70 72 65  umns in the [pre
245b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
245c0 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   S,.**          
245d0 20 6f 72 20 69 66 20 74 68 65 20 4e 74 68 20 63   or if the Nth c
245e0 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e  olumn of S is an
245f0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
24600 75 62 71 75 65 72 79 20 72 61 74 68 65 72 0a 2a  ubquery rather.*
24610 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61 6e  *           than
24620 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 2c   a table column,
24630 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20   or if a memory 
24640 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
24650 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  re.**           
24660 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 6e  occurs during en
24670 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f  coding conversio
24680 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  ns, then.**     
24690 20 20 20 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b        calls to [
246a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
246b0 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72  ecltype(S,N)] or
246c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
246d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
246e0 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 20 72  cltype16(S,N)] r
246f0 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63  eturn NULL..*/.c
24700 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
24710 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
24720 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
24730 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
24740 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
24750 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
24760 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
24770 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50 49 33 52 45  ../* .** CAPI3RE
24780 46 3a 20 20 45 76 61 6c 75 61 74 65 20 41 6e 20  F:  Evaluate An 
24790 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 46  SQL Statement {F
247a0 31 33 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 66 74  13200}.**.** Aft
247b0 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
247c0 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
247d0 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
247e0 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
247f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
24800 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
24810 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
24820 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
24830 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
24840 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
24850 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
24860 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
24870 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
24880 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
24890 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
248a0 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
248b0 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
248c0 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
248d0 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
248e0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
248f0 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
24900 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
24910 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
24920 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
24930 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
24940 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
24950 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24960 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
24970 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
24980 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
24990 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
249a0 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
249b0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
249c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
249d0 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
249e0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
249f0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
24a00 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
24a10 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
24a20 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
24a30 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
24a40 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
24a50 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
24a60 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
24a70 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
24a80 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
24a90 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
24aa0 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c  _BUSY], .** [SQL
24ab0 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
24ac0 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
24ad0 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
24ae0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
24af0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
24b00 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
24b10 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
24b20 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
24b30 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
24b40 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
24b50 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
24b60 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
24b70 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
24b80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
24b90 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
24ba0 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
24bb0 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
24bc0 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
24bd0 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65  its job.  If the
24be0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
24bf0 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63 63  COMMIT.** or occ
24c00 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
24c10 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
24c20 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
24c30 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
24c40 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
24c50 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
24c60 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 20 61  s not a COMMIT a
24c70 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
24c80 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74   a.** explicit t
24c90 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
24ca0 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
24cb0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
24cc0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
24cd0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
24ce0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
24cf0 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
24d00 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
24d10 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
24d20 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
24d30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
24d40 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
24d50 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
24d60 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
24d70 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
24d80 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
24d90 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
24da0 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
24db0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
24dc0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
24dd0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66   state..**.** If
24de0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
24df0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
24e00 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
24e10 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
24e20 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
24e30 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
24e40 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
24e50 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
24e60 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
24e70 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
24e80 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
24e90 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
24ea0 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
24eb0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
24ec0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
24ed0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
24ee0 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
24ef0 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
24f00 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  *.** [SQLITE_ERR
24f10 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
24f20 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
24f30 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
24f40 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
24f50 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
24f60 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
24f70 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
24f80 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
24f90 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
24fa0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
24fb0 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
24fc0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
24fd0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20  msg()]..** With 
24fe0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
24ff0 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
25000 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
25010 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
25020 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
25030 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
25040 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
25050 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
25060 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
25070 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
25080 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
25090 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
250a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
250b0 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22  ment].  In the "
250c0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
250d0 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
250e0 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
250f0 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
25100 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
25110 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
25120 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
25130 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
25140 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
25150 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
25160 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
25170 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
25180 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
25190 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
251a0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
251b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
251c0 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
251d0 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
251e0 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
251f0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
25200 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
25210 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
25220 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
25230 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
25240 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
25250 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
25260 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
25270 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
25280 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
25290 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
252a0 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
252b0 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
252c0 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
252d0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
252e0 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
252f0 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
25300 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
25310 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
25320 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
25330 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
25340 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
25350 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
25360 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
25370 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
25380 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
25390 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
253a0 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
253b0 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
253c0 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
253d0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
253e0 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
253f0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
25400 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
25410 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
25420 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
25430 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
25440 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
25450 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
25460 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
25470 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
25480 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
25490 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
254a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
254b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
254c0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
254d0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
254e0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
254f0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
25500 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25510 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
25520 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
25530 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
25540 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
25550 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
25560 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
25570 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
25580 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
25590 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
255a0 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  nded..**.** INVA
255b0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
255c0 31 33 32 30 32 7d 20 20 49 66 20 74 68 65 20 5b  13202}  If the [
255d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
255e0 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79 20 74  nt] S is ready t
255f0 6f 20 62 65 20 72 75 6e 2c 20 74 68 65 6e 0a 2a  o be run, then.*
25600 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
25610 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61 64  ite3_step(S)] ad
25620 76 61 6e 63 65 73 20 74 68 61 74 20 70 72 65 70  vances that prep
25630 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
25640 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ntil.**         
25650 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20    completion or 
25660 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61 64  until it is read
25670 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74  y to return anot
25680 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a  her row of the.*
25690 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 73 75  *           resu
256a0 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e 74 69 6c  lt set, or until
256b0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   an [sqlite3_int
256c0 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75  errupt | interru
256d0 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  pt].**          
256e0 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65   or a run-time e
256f0 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
25700 2a 2a 20 7b 46 31 35 33 30 34 7d 20 20 57 68 65  ** {F15304}  Whe
25710 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  n a call to [sql
25720 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63 61  ite3_step(S)] ca
25730 75 73 65 73 20 74 68 65 20 5b 70 72 65 70 61 72  uses the [prepar
25740 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
25750 20 20 20 20 20 20 20 20 20 20 20 53 20 74 6f 20             S to 
25760 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
25770 6e 2c 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  n, the function 
25780 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
25790 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  DONE]..**.** {F1
257a0 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63 61  5306}  When a ca
257b0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
257c0 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62 65  tep(S)] stops be
257d0 63 61 75 73 65 20 69 74 20 69 73 20 72 65 61 64  cause it is read
257e0 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  y to.**         
257f0 20 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72    return another
25800 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
25810 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74 75 72  lt set, it retur
25820 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e  ns [SQLITE_ROW].
25830 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 38 7d 20  .**.** {F15308} 
25840 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   If a call to [s
25850 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
25860 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a  encounters an.**
25870 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
25880 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20  te3_interrupt | 
25890 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20  interrupt] or a 
258a0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c 0a  run-time error,.
258b0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 20  **           it 
258c0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
258d0 70 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f 64  priate error cod
258e0 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f 6e  e that is not on
258f0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
25900 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b    [SQLITE_OK], [
25910 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72 20  SQLITE_ROW], or 
25920 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a  [SQLITE_DONE]..*
25930 2a 0a 2a 2a 20 7b 46 31 35 33 31 30 7d 20 20 49  *.** {F15310}  I
25940 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e  f an [sqlite3_in
25950 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72  terrupt | interr
25960 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69  upt] or a run-ti
25970 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20  me error.**     
25980 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72        occurs dur
25990 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
259a0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a  qlite3_step(S)].
259b0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f 72  **           for
259c0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
259d0 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65  tement] S create
259e0 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
259f0 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65       legacy inte
25a00 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
25a10 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a  prepare()] or.**
25a20 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
25a30 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
25a40 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74  , then the funct
25a50 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68  ion returns eith
25a60 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  er.**           
25a70 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
25a80 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f  [SQLITE_BUSY], o
25a90 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
25aa0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
25ab0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
25ac0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
25ad0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
25ae0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
25af0 65 73 75 6c 74 20 73 65 74 20 7b 46 31 33 37 37  esult set {F1377
25b00 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73  0}.**.** Returns
25b10 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76   the number of v
25b20 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72  alues in the cur
25b30 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
25b40 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a  result set..**.*
25b50 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
25b60 0a 2a 2a 20 7b 46 31 33 37 37 31 7d 20 20 41 66  .** {F13771}  Af
25b70 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ter a call to [s
25b80 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
25b90 74 68 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51  that returns [SQ
25ba0 4c 49 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20  LITE_ROW],.**   
25bb0 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
25bc0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
25bd0 53 29 5d 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  S)] routine will
25be0 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
25bf0 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20   value.**       
25c00 20 20 20 20 61 73 20 74 68 65 20 5b 73 71 6c 69      as the [sqli
25c10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
25c20 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  (S)] function..*
25c30 2a 0a 2a 2a 20 7b 46 31 33 37 37 32 7d 20 20 41  *.** {F13772}  A
25c40 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
25c50 65 70 28 53 29 5d 20 68 61 73 20 72 65 74 75 72  ep(S)] has retur
25c60 6e 65 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  ned any value ot
25c70 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
25c80 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f        [SQLITE_RO
25c90 57 5d 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71  W] or before [sq
25ca0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
25cb0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  as been called o
25cc0 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
25cd0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
25ce0 74 65 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20  tement] for the 
25cf0 66 69 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65  first time since
25d00 20 69 74 20 77 61 73 0a 2a 2a 20 20 20 20 20 20   it was.**      
25d10 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
25d20 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
25d30 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
25d40 73 65 74 20 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a  set | reset],.**
25d50 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b             the [
25d60 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
25d70 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 72  nt(S)] routine r
25d80 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a  eturns zero..*/.
25d90 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
25da0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
25db0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
25dc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
25dd0 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
25de0 70 65 73 20 7b 46 31 30 32 36 35 7d 0a 2a 2a 20  pes {F10265}.** 
25df0 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
25e00 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  _TEXT.**.** {F10
25e10 32 36 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65  266} Every value
25e20 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
25e30 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
25e40 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
25e50 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
25e60 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
25e70 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
25e80 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
25e90 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
25ea0 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
25eb0 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
25ec0 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
25ed0 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a   </ul> {END}.**.
25ee0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
25ef0 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
25f00 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
25f10 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
25f20 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
25f30 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
25f40 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
25f50 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
25f60 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
25f70 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
25f80 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
25f90 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
25fa0 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
25fb0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
25fc0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
25fd0 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
25fe0 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
25ff0 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
26000 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
26010 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
26020 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
26030 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
26040 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
26050 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26060 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
26070 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
26080 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
26090 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
260a0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
260b0 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
260c0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
260d0 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
260e0 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
260f0 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
26100 20 7b 46 31 33 38 30 30 7d 0a 2a 2a 20 4b 45 59   {F13800}.** KEY
26110 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
26120 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
26130 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
26140 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
26150 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 79  result set query
26160 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
26170 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
26180 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
26190 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
261a0 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
261b0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
261c0 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
261d0 72 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61  ry.  In every ca
261e0 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
261f0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
26200 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
26210 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26220 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
26230 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
26240 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
26250 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
26260 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
26270 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
26280 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
26290 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
262a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
262b0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
262c0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
262d0 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
262e0 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
262f0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
26300 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
26310 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
26320 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
26330 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
26340 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
26350 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
26360 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
26370 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
26380 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
26390 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
263a0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
263b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
263c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
263d0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
263e0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
263f0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
26400 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
26410 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
26420 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
26430 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
26440 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
26450 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
26460 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
26470 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
26480 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
26490 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
264a0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
264b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
264c0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
264d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
264e0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
264f0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
26500 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
26510 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
26520 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
26530 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
26540 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
26550 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
26560 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
26570 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
26580 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
26590 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
265a0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
265b0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
265c0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
265d0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
265e0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
265f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
26600 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
26610 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
26620 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
26630 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
26640 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
26650 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
26660 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
26670 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
26680 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75  olumn.  The retu
26690 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
266a0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
266b0 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
266c0 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
266d0 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
266e0 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
266f0 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
26700 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
26710 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
26720 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
26730 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
26740 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
26750 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
26760 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
26770 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
26780 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
26790 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
267a0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
267b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
267c0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
267d0 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
267e0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
267f0 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
26800 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
26810 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
26820 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
26830 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
26840 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  *.** If the resu
26850 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
26860 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
26870 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
26880 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
26890 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
268a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
268b0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
268c0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49   or string..** I
268d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
268e0 61 6e 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  an UTF-16 string
268f0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
26900 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
26910 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
26920 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
26930 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
26940 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
26950 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  es..** If the re
26960 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
26970 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
26980 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
26990 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
269a0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
269b0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
269c0 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 55 54 46   value to an UTF
269d0 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
269e0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
269f0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
26a00 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
26a10 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
26a20 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
26a30 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
26a40 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65  minator at the e
26a50 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
26a60 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74  ing.  For clarit
26a70 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  y: the value ret
26a80 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d  urned is the num
26a90 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
26aa0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
26ab0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
26ac0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
26ad0 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72  ** Strings retur
26ae0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
26af0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
26b00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26b10 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
26b20 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
26b30 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
26b40 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68   terminated.  Th
26b50 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
26b60 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
26b70 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
26b80 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62   a zero-length b
26b90 6c 6f 62 20 69 73 20 61 6e 20 61 72 62 69 74 72  lob is an arbitr
26ba0 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20  ary.** pointer, 
26bb0 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20  possibly even a 
26bc0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
26bd0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
26be0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
26bf0 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
26c00 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lar to sqlite3_c
26c10 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
26c20 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20   but leaves the 
26c30 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36  result in UTF-16
26c40 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
26c50 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
26c60 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a   UTF-8..** The z
26c70 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
26c80 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69  s not included i
26c90 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a  n this count..**
26ca0 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72  .** The object r
26cb0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
26cc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
26cd0 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
26ce0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26cf0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
26d00 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64    An unprotected
26d10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26d20 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  bject.** may onl
26d30 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b  y be used with [
26d40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
26d50 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
26d60 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
26d70 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
26d80 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
26d90 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
26da0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
26db0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26dc0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
26dd0 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
26de0 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
26df0 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
26e00 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
26e10 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
26e20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
26e30 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
26e40 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
26e50 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ()], then the be
26e60 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
26e70 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ned..**.** These
26e80 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
26e90 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
26ea0 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
26eb0 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a  ropriate.  For.*
26ec0 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
26ed0 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
26ee0 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
26ef0 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
26f00 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
26f10 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
26f20 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
26f30 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
26f40 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
26f50 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
26f60 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66  atically.  The f
26f70 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
26f80 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
26f90 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
26fa0 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
26fb0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
26fc0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
26fd0 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
26fe0 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
26ff0 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
27000 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
27010 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
27020 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
27030 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
27040 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
27050 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
27060 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
27070 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
27080 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
27090 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
270a0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
270b0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
270c0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
270d0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
270e0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
270f0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
27100 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
27110 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
27120 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
27130 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
27140 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
27150 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
27160 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
27170 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
27180 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
27190 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
271a0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
271b0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
271c0 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
271d0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
271e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
271f0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
27200 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f  Convert from flo
27210 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a  at to integer.**
27220 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
27230 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
27240 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
27250 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
27260 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
27270 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
27280 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
27290 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54  e as FLOAT->TEXT
272a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
272b0 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
272c0 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  ER   <td> Use at
272d0 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
272e0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
272f0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73  FLOAT    <td> Us
27300 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
27310 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
27320 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
27330 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
27340 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
27350 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
27360 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
27370 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
27380 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
27390 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
273a0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
273b0 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
273c0 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a  en use atof().**
273d0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
273e0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
273f0 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
27400 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
27410 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
27420 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
27430 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  te>.**.** The ta
27440 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
27450 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
27460 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
27470 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
27480 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
27490 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
274a0 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
274b0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
274c0 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
274d0 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
274e0 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
274f0 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
27500 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
27510 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
27520 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
27530 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
27540 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
27550 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
27560 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
27570 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
27580 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
27590 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
275a0 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
275b0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
275c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
275d0 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
275e0 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
275f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
27600 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
27610 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
27620 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
27630 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
27640 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
27650 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
27660 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
27670 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
27680 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
27690 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
276a0 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
276b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
276c0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
276d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
276e0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
276f0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
27700 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
27710 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
27720 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
27730 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
27740 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
27750 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
27760 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
27770 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
27780 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
27790 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
277a0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
277b0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
277c0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
277d0 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
277e0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
277f0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
27800 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
27810 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27820 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
27830 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27840 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
27850 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
27860 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
27870 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
27880 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
27890 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f  .**.** Conversio
278a0 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
278b0 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
278c0 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
278d0 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
278e0 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
278f0 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
27900 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
27910 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
27920 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
27930 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
27940 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20   pointer points 
27950 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  to will have bee
27960 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
27970 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
27980 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
27990 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
279a0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
279b0 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
279c0 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
279d0 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
279e0 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
279f0 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
27a00 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
27a10 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20   The safest and 
27a20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
27a30 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
27a40 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
27a50 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
27a60 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
27a70 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
27a80 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
27a90 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
27aa0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
27ab0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
27ac0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
27ad0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
27ae0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
27af0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
27b00 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
27b10 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
27b20 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
27b30 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
27b40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
27b50 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
27b60 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
27b70 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
27b80 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
27b90 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
27ba0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
27bb0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
27bc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
27bd0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
27be0 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
27bf0 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
27c00 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
27c10 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
27c20 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
27c30 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
27c40 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
27c50 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
27c60 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
27c70 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
27c80 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
27c90 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
27ca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
27cb0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
27cc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
27cd0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
27ce0 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
27cf0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
27d00 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
27d10 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
27d20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27d30 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tes()..**.** The
27d40 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
27d50 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
27d60 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
27d70 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
27d80 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
27d90 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
27da0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
27db0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
27dc0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
27dd0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
27de0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d  called.  The mem
27df0 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
27e00 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
27e10 2a 20 61 6e 64 20 62 6c 6f 62 73 20 69 73 20 66  * and blobs is f
27e20 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
27e30 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
27e40 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
27e50 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
27e60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
27e70 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
27e80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
27e90 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
27ea0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
27eb0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d  ..**.** If a mem
27ec0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
27ed0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
27ee0 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
27ef0 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
27f00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
27f10 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
27f20 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
27f30 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
27f40 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
27f50 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
27f60 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
27f70 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
27f80 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
27f90 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
27fa0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
27fb0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
27fc0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
27fd0 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  NOMEM]..**.** IN
27fe0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
27ff0 7b 46 31 33 38 30 33 7d 20 54 68 65 20 5b 73 71  {F13803} The [sq
28000 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
28010 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  b(S,N)] interfac
28020 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
28030 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
28040 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
28050 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
28060 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
28070 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
28080 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28090 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 42 4c 4f  nt] S into a BLO
280a0 42 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  B and then retur
280b0 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  ns a.**         
280c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
280d0 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e  converted value.
280e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 36 7d 20  .**.** {F13806} 
280f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
28100 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20  umn_bytes(S,N)] 
28110 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28120 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
28130 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
28140 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72  s in the BLOB or
28150 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
28160 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
28170 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
28180 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
28190 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
281a0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
281b0 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
281c0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
281d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
281e0 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20  ob(S,N)] or.**  
281f0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
28200 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e  _column_text(S,N
28210 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30  )]..**.** {F1380
28220 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
28230 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 53  column_bytes16(S
28240 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
28250 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
28260 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
28270 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
28280 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20  ring (exclusive 
28290 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
282a0 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74     zero terminat
282b0 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67  or on the string
282c0 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ) that was retur
282d0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ned by the.**   
282e0 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65         most rece
282f0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
28300 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
28310 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  6(S,N)]..**.** {
28320 46 31 33 38 31 32 7d 20 54 68 65 20 5b 73 71 6c  F13812} The [sql
28330 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
28340 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  le(S,N)] interfa
28350 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
28360 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
28370 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
28380 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
28390 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20   result set for 
283a0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
283b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
283c0 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c  ent] S into a fl
283d0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
283e0 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ue and.**       
283f0 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70     returns a cop
28400 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e  y of that value.
28410 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 35 7d 20  .**.** {F13815} 
28420 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
28430 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e  umn_int(S,N)] in
28440 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
28450 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
28460 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
28470 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
28480 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
28490 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
284a0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
284b0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
284c0 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
284d0 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20   integer and.** 
284e0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
284f0 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69   the lower 32 bi
28500 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67  ts of that integ
28510 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31  er..**.** {F1381
28520 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
28530 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e  column_int64(S,N
28540 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
28550 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
28560 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
28570 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
28580 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
28590 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a  t set for the.**
285a0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
285b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
285c0 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
285d0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
285e0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
285f0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
28600 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  that integer..**
28610 0a 2a 2a 20 7b 46 31 33 38 32 31 7d 20 54 68 65  .** {F13821} The
28620 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28630 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 6e 74 65  _text(S,N)] inte
28640 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
28650 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
28660 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
28670 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
28680 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
28690 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
286a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
286b0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
286c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
286d0 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20   UTF-8.**       
286e0 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
286f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
28700 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
28710 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 34 7d 20 54  **.** {F13824} T
28720 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
28730 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 20  mn_text16(S,N)] 
28740 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
28750 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
28760 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
28770 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
28780 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
28790 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  et for the.**   
287a0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
287b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
287c0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
287d0 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20  ated 2-byte.**  
287e0 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20          aligned 
287f0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
28800 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67 20  te order string 
28810 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  and returns.**  
28820 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65          a pointe
28830 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
28840 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 37 7d  ..**.** {F13827}
28850 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
28860 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20  lumn_type(S,N)] 
28870 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28880 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e  s.**          on
28890 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  e of [SQLITE_NUL
288a0 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  L], [SQLITE_INTE
288b0 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c  GER], [SQLITE_FL
288c0 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  OAT],.**        
288d0 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c    [SQLITE_TEXT],
288e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42   or [SQLITE_BLOB
288f0 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65  ] as appropriate
28900 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
28910 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
28920 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
28930 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
28940 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
28950 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72       the [prepar
28960 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
28970 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 33 30 7d 20  .**.** {F13830} 
28980 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
28990 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20  umn_value(S,N)] 
289a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
289b0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
289c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75  pointer to an [u
289d0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
289e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
289f0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
28a00 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
28a10 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
28a20 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
28a30 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
28a40 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72       the [prepar
28a50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
28a60 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
28a70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28a80 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
28a90 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
28aa0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
28ab0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
28ac0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
28ad0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
28ae0 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
28af0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
28b00 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
28b10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
28b20 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
28b30 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
28b40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28b50 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
28b60 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
28b70 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
28b80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
28b90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28ba0 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
28bb0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
28bc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28bd0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
28be0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
28bf0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
28c00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
28c10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28c20 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
28c30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
28c40 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
28c50 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
28c60 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
28c70 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
28c80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28c90 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
28ca0 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
28cb0 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
28cc0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
28cd0 46 31 33 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13300}.**.** Th
28ce0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
28cf0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
28d00 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
28d10 65 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65  e a .** [prepare
28d20 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 49 66  d statement]. If
28d30 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
28d40 61 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 73  as.** executed s
28d50 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 6f 72 20  uccessfully, or 
28d60 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20  not executed at 
28d70 61 6c 6c 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  all, then SQLITE
28d80 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
28d90 0a 2a 2a 20 49 66 20 65 78 65 63 75 74 69 6f 6e  .** If execution
28da0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
28db0 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e  t failed then an
28dc0 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65   .** [error code
28dd0 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
28de0 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73  rror code].** is
28df0 20 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a   returned. .**.*
28e00 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
28e10 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
28e20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
28e30 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
28e40 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
28e50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
28e60 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d  If the virtual m
28e70 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 20 0a  achine has not .
28e80 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
28e90 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73  cution when this
28ea0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
28eb0 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65  ed, that is like
28ec0 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  .** encountering
28ed0 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20   an error or an 
28ee0 69 6e 74 65 72 72 75 70 74 2e 20 20 28 53 65 65  interrupt.  (See
28ef0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
28f00 75 70 74 28 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63  upt()].) .** Inc
28f10 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20  omplete updates 
28f20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  may be rolled ba
28f30 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69  ck and transacti
28f40 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 20 20 0a  ons canceled,  .
28f50 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ** depending on 
28f60 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  the circumstance
28f70 73 2c 20 61 6e 64 20 74 68 65 20 0a 2a 2a 20 5b  s, and the .** [
28f80 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75  error code] retu
28f90 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51  rned will be [SQ
28fa0 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a  LITE_ABORT]..**.
28fb0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
28fc0 2a 0a 2a 2a 20 7b 46 31 31 33 30 32 7d 20 54 68  *.** {F11302} Th
28fd0 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  e [sqlite3_final
28fe0 69 7a 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63  ize(S)] interfac
28ff0 65 20 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a  e destroys the.*
29000 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
29010 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29020 53 20 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61  S and releases a
29030 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ll.**          m
29040 65 6d 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72  emory and file r
29050 65 73 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79  esources held by
29060 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a   that object..**
29070 0a 2a 2a 20 7b 46 31 31 33 30 34 7d 20 49 66 20  .** {F11304} If 
29080 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
29090 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
290a0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
290b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
290c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
290d0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e  t] S returned an
290e0 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20   error,.**      
290f0 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
29100 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72  3_finalize(S)] r
29110 65 74 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65  eturns that same
29120 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73   error..*/.int s
29130 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29140 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
29150 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
29160 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
29170 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
29180 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 33 33 30  t Object {F13330
29190 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
291a0 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
291b0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
291c0 6f 20 72 65 73 65 74 20 61 20 0a 2a 2a 20 5b 70  o reset a .** [p
291d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
291e0 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 62 61  t] object..** ba
291f0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
29200 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
29210 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
29220 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61  ..** Any SQL sta
29230 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
29240 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
29250 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
29260 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
29270 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
29280 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
29290 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
292a0 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
292b0 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
292c0 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
292d0 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
292e0 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33  ngs..**.** {F113
292f0 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  32} The [sqlite3
29300 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
29310 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
29320 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29330 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20  ent] S.**       
29340 20 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62     back to the b
29350 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
29360 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b  program..**.** {
29370 46 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d  F11334} If the m
29380 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
29390 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
293a0 28 53 29 5d 20 66 6f 72 20 0a 2a 2a 20 20 20 20  (S)] for .**    
293b0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
293c0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
293d0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
293e0 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  W] or [SQLITE_DO
293f0 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NE],.**         
29400 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
29410 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
29420 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
29430 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20  alled on S,.**  
29440 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71          then [sq
29450 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
29460 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
29470 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33  OK]..**.** {F113
29480 33 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  36} If the most 
29490 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
294a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
294b0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
294c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
294d0 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
294e0 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
294f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
29500 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
29510 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
29520 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
29530 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33  de]..**.** {F113
29540 33 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  38} The [sqlite3
29550 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
29560 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68  face does not ch
29570 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a  ange the values.
29580 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61  **          of a
29590 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
295a0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
295b0 6f 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  on [prepared sta
295c0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e  tement] S..*/.in
295d0 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
295e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
295f0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
29600 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
29610 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
29620 6e 63 74 69 6f 6e 73 20 7b 46 31 36 31 30 30 7d  nctions {F16100}
29630 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
29640 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
29650 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
29660 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
29670 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
29680 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
29690 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
296a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
296b0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
296c0 2a 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63  * These two func
296d0 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
296e0 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 0a 2a 2a 20  ely known as.** 
296f0 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
29700 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 20 61 72  on routines") ar
29710 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
29720 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
29730 67 67 72 65 67 61 74 65 73 0a 2a 2a 20 6f 72 20  ggregates.** or 
29740 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
29750 62 65 68 61 76 69 6f 72 20 6f 66 20 65 78 69 73  behavior of exis
29760 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
29770 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
29780 2e 20 20 54 68 65 0a 2a 2a 20 64 69 66 66 65 72  .  The.** differ
29790 65 6e 63 65 20 6f 6e 6c 79 20 62 65 74 77 65 65  ence only betwee
297a0 6e 20 74 68 65 20 74 77 6f 20 69 73 20 74 68 61  n the two is tha
297b0 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  t the second par
297c0 61 6d 65 74 65 72 2c 20 74 68 65 0a 2a 2a 20 6e  ameter, the.** n
297d0 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c  ame of the (scal
297e0 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  ar) function or 
297f0 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e  aggregate, is en
29800 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66  coded in UTF-8 f
29810 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  or.** sqlite3_cr
29820 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
29830 61 6e 64 20 55 54 46 2d 31 36 20 66 6f 72 20 73  and UTF-16 for s
29840 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
29850 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a  nction16()..**.*
29860 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
29870 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
29880 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29890 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
298a0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
298b0 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
298c0 20 49 66 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   If a single.** 
298d0 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72  program uses mor
298e0 65 20 74 68 61 6e 20 6f 6e 65 20 5b 64 61 74 61  e than one [data
298f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
29900 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65   internally, the
29910 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  n SQL.** functio
29920 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
29930 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f   individually to
29940 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20   each [database 
29950 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  connection]..**.
29960 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
29970 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
29980 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
29990 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
299a0 65 61 74 65 64 0a 2a 2a 20 6f 72 20 72 65 64 65  eated.** or rede
299b0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6c 65  fined..** The le
299c0 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
299d0 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
299e0 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73  55 bytes, exclus
299f0 69 76 65 20 6f 66 20 74 68 65 20 0a 2a 2a 20 7a  ive of the .** z
29a00 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
29a10 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e   Note that the n
29a20 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  ame length limit
29a30 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f   is in bytes, no
29a40 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e  t.** characters.
29a50 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f    Any attempt to
29a60 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
29a70 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
29a80 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
29a90 73 75 6c 74 20 69 6e 20 61 6e 20 53 51 4c 49 54  sult in an SQLIT
29aa0 45 5f 45 52 52 4f 52 20 65 72 72 6f 72 2e 0a 2a  E_ERROR error..*
29ab0 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70  *.** The third p
29ac0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
29ad0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
29ae0 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
29af0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
29b00 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
29b10 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   If this paramet
29b20 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
29b30 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
29b40 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
29b50 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
29b60 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
29b70 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  uments..**.** Th
29b80 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
29b90 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
29ba0 65 63 69 66 69 65 73 20 77 68 61 74 20 0a 2a 2a  ecifies what .**
29bb0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
29bc0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
29bd0 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
29be0 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
29bf0 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
29c00 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f   Any SQL functio
29c10 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
29c20 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20   should be able 
29c30 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20  to work.** work 
29c40 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
29c50 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
29c60 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
29c70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
29c80 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
29c90 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
29ca0 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
29cb0 74 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c  ther.  It is all
29cc0 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  owed to.** invok
29cd0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
29ce0 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73  _function() or s
29cf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
29d00 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69  nction16() multi
29d10 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
29d20 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  h the same funct
29d30 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66  ion but with dif
29d40 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66  ferent values of
29d50 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68   eTextRep..** Wh
29d60 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
29d70 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
29d80 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
29d90 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
29da0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
29db0 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
29dc0 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
29dd0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
29de0 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
29df0 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e  * If there is on
29e00 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c  ly a single impl
29e10 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68  ementation which
29e20 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77   does not care w
29e30 68 61 74 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  hat.** text enco
29e40 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ding is used, th
29e50 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  en the fourth ar
29e60 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
29e70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d  .** [SQLITE_ANY]
29e80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
29e90 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
29ea0 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
29eb0 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
29ec0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74  entation.** of t
29ed0 68 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  he function can 
29ee0 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
29ef0 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
29f00 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 75 73  g.** [sqlite3_us
29f10 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a  er_data()]..**.*
29f20 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65  * The seventh, e
29f30 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20  ighth and ninth 
29f40 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
29f50 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
29f60 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
29f70 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
29f80 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
29f90 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
29fa0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
29fb0 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 41 20  or aggregate. A 
29fc0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
29fd0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
29fe0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
29ff0 66 0a 2a 2a 20 74 68 65 20 78 46 75 6e 63 20 63  f.** the xFunc c
2a000 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55  allback only, NU
2a010 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75  LL pointers shou
2a020 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20  ld be passed as 
2a030 74 68 65 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64  the xStep.** and
2a040 20 78 46 69 6e 61 6c 20 70 61 72 61 6d 65 74 65   xFinal paramete
2a050 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65  rs. An aggregate
2a060 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
2a070 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
2a080 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 78  entation.** of x
2a090 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 20  Step and xFinal 
2a0a0 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20  and NULL should 
2a0b0 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
2a0c0 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61  unc. To delete a
2a0d0 6e 0a 2a 2a 20 65 78 69 73 74 69 6e 67 20 53 51  n.** existing SQ
2a0e0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
2a0f0 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
2a100 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  LL for all three
2a110 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
2a120 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74  lbacks..**.** It
2a130 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
2a140 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
2a150 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2a160 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
2a170 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
2a180 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
2a190 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
2a1a0 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
2a1b0 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
2a1c0 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
2a1d0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2a1e0 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20  odings.  SQLite 
2a1f0 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
2a200 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
2a210 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
2a220 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
2a230 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
2a240 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
2a250 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2a260 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30  TS:.**.** {F1610
2a270 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2a280 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2a290 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  6()] interface b
2a2a0 65 68 61 76 65 73 20 65 78 61 63 74 6c 79 0a 2a  ehaves exactly.*
2a2b0 2a 20 20 20 20 20 20 20 20 20 20 6c 69 6b 65 20  *          like 
2a2c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2a2d0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 69 6e 20 65  function()] in e
2a2e0 76 65 72 79 20 77 61 79 20 65 78 63 65 70 74 20  very way except 
2a2f0 74 68 61 74 20 69 74 0a 2a 2a 20 20 20 20 20 20  that it.**      
2a300 20 20 20 20 69 6e 74 65 72 70 72 65 74 73 20 74      interprets t
2a310 68 65 20 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  he zFunctionName
2a320 20 61 72 67 75 6d 65 6e 74 20 61 73 0a 2a 2a 20   argument as.** 
2a330 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
2a340 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20  rminated UTF-16 
2a350 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2a360 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 73 20  r instead of as 
2a370 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  a.**          ze
2a380 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2a390 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  F-8..**.** {F161
2a3a0 30 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  06} A successful
2a3b0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
2a3c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
2a3d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2a3e0 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
2a3f0 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
2a400 72 65 67 69 73 74 65 72 73 0a 2a 2a 20 20 20 20  registers.**    
2a410 20 20 20 20 20 20 6f 72 20 72 65 70 6c 61 63 65        or replace
2a420 73 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  s callback funct
2a430 69 6f 6e 73 20 69 6e 20 5b 64 61 74 61 62 61 73  ions in [databas
2a440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
2a450 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65 64  **          used
2a460 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
2a470 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e  e SQL function n
2a480 61 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70 61  amed X with N pa
2a490 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20  rameters.**     
2a4a0 20 20 20 20 20 61 6e 64 20 68 61 76 69 6e 67 20       and having 
2a4b0 61 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  a preferred text
2a4c0 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a   encoding of E..
2a4d0 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 39 7d 20 41  **.** {F16109} A
2a4e0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
2a4f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2a500 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2a510 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a  ,N,E,P,F,S,L)].*
2a520 2a 20 20 20 20 20 20 20 20 20 20 72 65 70 6c 61  *          repla
2a530 63 65 73 20 74 68 65 20 50 2c 20 46 2c 20 53 2c  ces the P, F, S,
2a540 20 61 6e 64 20 4c 20 76 61 6c 75 65 73 20 66 72   and L values fr
2a550 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c  om any prior cal
2a560 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20  ls with.**      
2a570 20 20 20 20 74 68 65 20 73 61 6d 65 20 44 2c 20      the same D, 
2a580 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c 75  X, N, and E valu
2a590 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31  es..**.** {F1611
2a5a0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2a5b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2a5c0 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  D,X,...)] interf
2a5d0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 0a 2a  ace fails with.*
2a5e0 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74  *          a ret
2a5f0 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  urn code of [SQL
2a600 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 74 68  ITE_ERROR] if th
2a610 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e  e SQL function n
2a620 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20 20 20  ame X is.**     
2a630 20 20 20 20 20 6c 6f 6e 67 65 72 20 74 68 61 6e       longer than
2a640 20 32 35 35 20 62 79 74 65 73 20 65 78 63 6c 75   255 bytes exclu
2a650 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
2a660 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
2a670 2a 2a 20 7b 46 31 36 31 31 38 7d 20 45 69 74 68  ** {F16118} Eith
2a680 65 72 20 46 20 6d 75 73 74 20 62 65 20 4e 55 4c  er F must be NUL
2a690 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72  L and S and L ar
2a6a0 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 20 65 6c  e non-NULL or el
2a6b0 73 65 20 46 0a 2a 2a 20 20 20 20 20 20 20 20 20  se F.**         
2a6c0 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64   is non-NULL and
2a6d0 20 53 20 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c   S and L are NUL
2a6e0 4c 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20  L, otherwise.** 
2a6f0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2a700 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2a710 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  n(D,X,N,E,P,F,S,
2a720 4c 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  L)] returns [SQL
2a730 49 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a  ITE_ERROR]..**.*
2a740 2a 20 7b 46 31 36 31 32 31 7d 20 54 68 65 20 5b  * {F16121} The [
2a750 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2a760 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20  unction(D,...)] 
2a770 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
2a780 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20  with an.**      
2a790 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f      error code o
2a7a0 66 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  f [SQLITE_BUSY] 
2a7b0 69 66 20 74 68 65 72 65 20 65 78 69 73 74 20 5b  if there exist [
2a7c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a7d0 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  nts].**         
2a7e0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2a7f0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2a800 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
2a810 0a 2a 2a 20 7b 46 31 36 31 32 34 7d 20 54 68 65  .** {F16124} The
2a820 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2a830 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2a840 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
2a850 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a  fails with an.**
2a860 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20            error 
2a870 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
2a880 45 52 52 4f 52 5d 20 69 66 20 70 61 72 61 6d 65  ERROR] if parame
2a890 74 65 72 20 4e 20 28 73 70 65 63 69 66 79 69 6e  ter N (specifyin
2a8a0 67 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  g the number.** 
2a8b0 20 20 20 20 20 20 20 20 20 6f 66 20 61 72 67 75           of argu
2a8c0 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c  ments to the SQL
2a8d0 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20   function being 
2a8e0 72 65 67 69 73 74 65 72 65 64 29 20 69 73 20 6c  registered) is l
2a8f0 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ess.**          
2a900 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
2a910 65 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a  er than 127..**.
2a920 2a 2a 20 7b 46 31 36 31 32 37 7d 20 57 68 65 6e  ** {F16127} When
2a930 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
2a940 76 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ve, the [sqlite3
2a950 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2a960 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20  (D,X,N,...)].** 
2a970 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
2a980 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61  ce causes callba
2a990 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  cks to be invoke
2a9a0 64 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75  d for the SQL fu
2a9b0 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
2a9c0 20 20 20 6e 61 6d 65 64 20 58 20 77 68 65 6e 20     named X when 
2a9d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
2a9e0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53  guments to the S
2a9f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  QL function is.*
2aa00 2a 20 20 20 20 20 20 20 20 20 20 65 78 61 63 74  *          exact
2aa10 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ly N..**.** {F16
2aa20 31 33 30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d  130} When N is -
2aa30 31 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  1, the [sqlite3_
2aa40 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2aa50 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  D,X,N,...)].**  
2aa60 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
2aa70 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63  e causes callbac
2aa80 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ks to be invoked
2aa90 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e   for the SQL fun
2aaa0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
2aab0 20 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 61    named X with a
2aac0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
2aad0 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  uments..**.** {F
2aae0 31 36 31 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c  16133} When call
2aaf0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  s to [sqlite3_cr
2ab00 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2ab10 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  X,N,...)].**    
2ab20 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75        specify mu
2ab30 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2ab40 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2ab50 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a  me function X.**
2ab60 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68            and wh
2ab70 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74  en one implement
2ab80 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61  ation has N>=0 a
2ab90 6e 64 20 74 68 65 20 6f 74 68 65 72 20 68 61 73  nd the other has
2aba0 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20   N=(-1).**      
2abb0 20 20 20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e      the implemen
2abc0 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
2abd0 6e 2d 7a 65 72 6f 20 4e 20 69 73 20 70 72 65 66  n-zero N is pref
2abe0 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  erred..**.** {F1
2abf0 36 31 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73  6136} When calls
2ac00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2ac10 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2ac20 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  ,N,E,...)].**   
2ac30 20 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d         specify m
2ac40 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2ac50 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2ac60 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 20 77  ame function X w
2ac70 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
2ac80 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20  the same number 
2ac90 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20 62  of arguments N b
2aca0 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
2acb0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e  t.**          en
2acc0 63 6f 64 69 6e 67 73 20 45 2c 20 74 68 65 6e 20  codings E, then 
2acd0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2ace0 6f 6e 20 77 68 65 72 65 20 45 20 6d 61 74 63 68  on where E match
2acf0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2ad00 20 20 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f     database enco
2ad10 64 69 6e 67 20 69 73 20 70 72 65 66 65 72 72 65  ding is preferre
2ad20 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 39  d..**.** {F16139
2ad30 7d 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67 61  } For an aggrega
2ad40 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
2ad50 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
2ad60 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2ad70 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ad80 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53  on(D,X,N,E,P,0,S
2ad90 2c 4c 29 5d 20 74 68 65 20 66 69 6e 69 61 6c 69  ,L)] the finiali
2ada0 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  zer.**          
2adb0 66 75 6e 63 74 69 6f 6e 20 4c 20 77 69 6c 6c 20  function L will 
2adc0 61 6c 77 61 79 73 20 62 65 20 69 6e 76 6f 6b 65  always be invoke
2add0 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69  d exactly once i
2ade0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2adf0 20 20 73 74 65 70 20 66 75 6e 63 74 69 6f 6e 20    step function 
2ae00 53 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20  S is called one 
2ae10 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
2ae20 2a 0a 2a 2a 20 7b 46 31 36 31 34 32 7d 20 57 68  *.** {F16142} Wh
2ae30 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
2ae40 73 20 65 69 74 68 65 72 20 74 68 65 20 78 46 75  s either the xFu
2ae50 6e 63 20 6f 72 20 78 53 74 65 70 20 66 75 6e 63  nc or xStep func
2ae60 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20  tion of.**      
2ae70 20 20 20 20 61 6e 20 61 70 70 6c 69 63 61 74 69      an applicati
2ae80 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2ae90 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
2aea0 67 61 74 65 20 63 72 65 61 74 65 64 0a 2a 2a 20  gate created.** 
2aeb0 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c           by [sql
2aec0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2aed0 74 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69  tion()] or [sqli
2aee0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2aef0 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20  ion16()],.**    
2af00 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 61        then the a
2af10 72 72 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 33  rray of [sqlite3
2af20 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20  _value] objects 
2af30 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
2af40 20 20 20 20 20 20 20 20 20 20 74 68 69 72 64 20            third 
2af50 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 61 6c  parameter are al
2af60 77 61 79 73 20 5b 70 72 6f 74 65 63 74 65 64 20  ways [protected 
2af70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2af80 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73  bjects..*/.int s
2af90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2afa0 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
2afb0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
2afc0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
2afd0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2afe0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2aff0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2b000 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2b010 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2b020 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2b030 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2b040 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2b050 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2b060 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2b070 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2b080 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2b090 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2b0a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2b0b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
2b0c0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
2b0d0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
2b0e0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
2b0f0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
2b100 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
2b110 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
2b120 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2b130 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2b140 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
2b150 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2b160 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2b170 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
2b180 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
2b190 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  ntext*).);../*.*
2b1a0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
2b1b0 20 45 6e 63 6f 64 69 6e 67 73 20 7b 46 31 30 32   Encodings {F102
2b1c0 36 37 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  67}.**.** These 
2b1d0 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
2b1e0 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
2b1f0 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
2b200 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
2b210 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
2b220 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
2b230 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2b240 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
2b250 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2b260 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
2b270 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2b280 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
2b290 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
2b2a0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
2b2b0 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
2b2c0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
2b2d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2b2e0 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
2b2f0 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  5    /* sqlite3_
2b300 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20  create_function 
2b310 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
2b320 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
2b330 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
2b340 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2b350 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
2b360 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b370 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f  Obsolete Functio
2b380 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ns.**.** These f
2b390 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c  unctions are all
2b3a0 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20   now obsolete.  
2b3b0 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
2b3c0 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
2b3d0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
2b3e0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
2b3f0 20 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   we continue to 
2b400 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65  support.** these
2b410 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77   functions.  How
2b420 65 76 65 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f  ever, new develo
2b430 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 20 73  pment projects s
2b440 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
2b450 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
2b460 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
2b470 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
2b480 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
2b490 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
2b4a0 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
2b4b0 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
2b4c0 20 79 6f 75 20 77 61 6e 74 20 74 68 65 79 20 64   you want they d
2b4d0 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  o..*/.int sqlite
2b4e0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
2b4f0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2b500 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
2b510 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
2b520 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c  _stmt*);.int sql
2b530 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
2b540 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2b550 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
2b560 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  mt*);.int sqlite
2b570 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
2b580 28 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c  (void);.void sql
2b590 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
2b5a0 6e 75 70 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  nup(void);.int s
2b5b0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
2b5c0 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64  arm(void(*)(void
2b5d0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  *,sqlite3_int64,
2b5e0 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74  int),void*,sqlit
2b5f0 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a  e3_int64);../*.*
2b600 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
2b610 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
2b620 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
2b630 75 65 73 20 7b 46 31 35 31 30 30 7d 0a 2a 2a 0a  ues {F15100}.**.
2b640 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
2b650 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2b660 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
2b670 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
2b680 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
2b690 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
2b6a0 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
2b6b0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
2b6c0 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
2b6d0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2b6e0 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
2b6f0 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
2b700 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
2b710 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
2b720 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
2b730 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
2b740 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2b750 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
2b760 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2b770 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
2b780 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
2b790 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
2b7a0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
2b7b0 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
2b7c0 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  The 4th paramete
2b7d0 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
2b7e0 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
2b7f0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
2b800 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
2b810 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2b820 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
2b830 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
2b840 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
2b850 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
2b860 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
2b870 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
2b880 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
2b890 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
2b8a0 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
2b8b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2b8c0 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
2b8d0 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
2b8e0 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
2b8f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b900 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
2b910 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
2b920 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
2b930 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
2b940 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b950 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
2b960 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
2b970 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
2b980 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2b990 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65  s work just like
2b9a0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2b9b0 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  ng [column acces
2b9c0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20  s functions].** 
2b9d0 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65  except that  the
2b9e0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
2b9f0 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
2ba00 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2ba10 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f  ue] object.** po
2ba20 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
2ba30 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
2ba40 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
2ba50 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
2ba60 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   number..**.** T
2ba70 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2ba80 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66  _text16() interf
2ba90 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55  ace extracts a U
2baa0 54 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  TF16 string.** i
2bab0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
2bac0 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
2bad0 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68  ost machine.  Th
2bae0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
2baf0 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
2bb00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
2bb10 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
2bb20 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
2bb30 20 55 54 46 31 36 20 73 74 72 69 6e 67 73 20 61   UTF16 strings a
2bb40 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
2bb50 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
2bb60 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
2bb70 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
2bb80 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2bb90 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
2bba0 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
2bbb0 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
2bbc0 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
2bbd0 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
2bbe0 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
2bbf0 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
2bc00 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
2bc10 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
2bc20 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
2bc30 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
2bc40 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
2bc50 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
2bc60 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
2bc70 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
2bc80 64 73 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ds if the value 
2bc90 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
2bca0 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
2bcb0 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
2bcc0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
2bcd0 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69 73 65  done.  Otherwise
2bce0 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
2bcf0 63 63 75 72 73 2e 20 20 54 68 65 20 0a 2a 2a 20  ccurs.  The .** 
2bd00 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2bd10 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
2bd20 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
2bd30 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2bd40 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
2bd50 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
2bd60 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
2bd70 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
2bd80 74 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  t.** is returned
2bd90 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
2bda0 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
2bdb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2bdc0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
2bdd0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2bde0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
2bdf0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
2be00 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
2be10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2be20 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
2be30 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2be40 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
2be50 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2be60 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2be70 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 20 20  lue_text16()].  
2be80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2be90 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
2bea0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2beb0 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
2bec0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2bed0 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
2bee0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2bef0 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
2bf00 2a 2a 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  **.**.** INVARIA
2bf10 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  NTS:.**.** {F151
2bf20 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  03} The [sqlite3
2bf30 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20  _value_blob(V)] 
2bf40 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2bf50 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2bf60 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2bf70 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2bf80 65 63 74 20 56 20 69 6e 74 6f 20 61 20 62 6c 6f  ect V into a blo
2bf90 62 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  b and then retur
2bfa0 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  ns a.**         
2bfb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2bfc0 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e  converted value.
2bfd0 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 36 7d 20  .**.** {F15106} 
2bfe0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2bff0 75 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e 74  ue_bytes(V)] int
2c000 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2c010 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
2c020 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2c030 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73 74  n the blob or st
2c040 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20  ring (exclusive 
2c050 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
2c060 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74     zero terminat
2c070 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67  or on the string
2c080 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ) that was retur
2c090 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ned by the.**   
2c0a0 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65         most rece
2c0b0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2c0c0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56  te3_value_blob(V
2c0d0 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
2c0e0 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65    [sqlite3_value
2c0f0 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a  _text(V)]..**.**
2c100 20 7b 46 31 35 31 30 39 7d 20 54 68 65 20 5b 73   {F15109} The [s
2c110 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2c120 65 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61  es16(V)] interfa
2c130 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ce returns the.*
2c140 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
2c150 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2c160 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  e string (exclus
2c170 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
2c180 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
2c190 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
2c1a0 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
2c1b0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2c1c0 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
2c1d0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2c1e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2c1f0 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20  xt16(V)],.**    
2c200 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76        [sqlite3_v
2c210 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29  alue_text16be(V)
2c220 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ], or [sqlite3_v
2c230 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29  alue_text16le(V)
2c240 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 32  ]..**.** {F15112
2c250 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2c260 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20  alue_double(V)] 
2c270 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2c280 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2c290 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2c2a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2c2b0 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f  ect V into a flo
2c2c0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
2c2d0 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  e and.**        
2c2e0 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
2c2f0 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a   of that value..
2c300 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 35 7d 20 54  **.** {F15115} T
2c310 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2c320 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72 66  e_int(V)] interf
2c330 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2c340 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2c350 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c360 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2c370 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69  into a 64-bit si
2c380 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
2c390 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2c3a0 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33  urns the lower 3
2c3b0 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69  2 bits of that i
2c3c0 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nteger..**.** {F
2c3d0 31 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69  15118} The [sqli
2c3e0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
2c3f0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2c400 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2c410 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
2c420 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2c430 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
2c440 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2c450 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
2c460 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
2c470 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e   copy of that in
2c480 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  teger..**.** {F1
2c490 35 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  5121} The [sqlit
2c4a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29  e3_value_text(V)
2c4b0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2c4c0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2c4d0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2c4e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c4f0 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a  bject V into a z
2c500 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2c510 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20 20 20  TF-8 .**        
2c520 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
2c530 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2c540 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
2c550 2a 0a 2a 2a 20 7b 46 31 35 31 32 34 7d 20 54 68  *.** {F15124} Th
2c560 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2c570 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65  _text16(V)] inte
2c580 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2c590 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2c5a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c5b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2c5c0 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
2c5d0 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
2c5e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
2c5f0 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ned UTF-16 nativ
2c600 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
2c610 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2c620 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2c630 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2c640 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ring..**.** {F15
2c650 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  127} The [sqlite
2c660 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
2c670 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2c680 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2c690 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2c6a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c6b0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2c6c0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2c6d0 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
2c6e0 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
2c6f0 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a  -16 big-endian.*
2c700 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
2c710 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
2c720 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2c730 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46  string..**.** {F
2c740 31 35 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69  15130} The [sqli
2c750 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2c760 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  le(V)] interface
2c770 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2c780 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2c790 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c7a0 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2c7b0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2c7c0 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20  ted 2-byte.**   
2c7d0 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55         aligned U
2c7e0 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  TF-16 little-end
2c7f0 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ian.**          
2c800 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2c810 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2c820 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
2c830 2a 2a 20 7b 46 31 35 31 33 33 7d 20 54 68 65 20  ** {F15133} The 
2c840 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2c850 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ype(V)] interfac
2c860 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
2c870 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51        one of [SQ
2c880 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_NULL], [SQL
2c890 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53  ITE_INTEGER], [S
2c8a0 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a  QLITE_FLOAT],.**
2c8b0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2c8c0 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c  E_TEXT], or [SQL
2c8d0 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70  ITE_BLOB] as app
2c8e0 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20  ropriate for.** 
2c8f0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
2c900 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2c910 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ect V..**.** {F1
2c920 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  5136} The [sqlit
2c930 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2c940 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66  _type(V)] interf
2c950 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  ace converts.** 
2c960 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
2c970 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c980 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2c990 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69  into either an i
2c9a0 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20  nteger or.**    
2c9b0 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67        a floating
2c9c0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20   point value if 
2c9d0 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74  it can do so wit
2c9e0 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20  hout loss of.** 
2c9f0 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61           informa
2ca00 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e  tion, and return
2ca10 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2ca20 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20  _NULL],.**      
2ca30 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45      [SQLITE_INTE
2ca40 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c  GER], [SQLITE_FL
2ca50 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
2ca60 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  XT], or.**      
2ca70 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42      [SQLITE_BLOB
2ca80 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65  ] as appropriate
2ca90 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
2caa0 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20   the [protected 
2cab0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2cac0 62 6a 65 63 74 20 56 20 61 66 74 65 72 20 74 68  bject V after th
2cad0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74  e conversion att
2cae0 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  empt..*/.const v
2caf0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2cb00 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
2cb10 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2cb20 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2cb30 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2cb40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2cb50 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
2cb60 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
2cb70 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
2cb80 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
2cb90 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2cba0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2cbb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2cbc0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
2cbd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2cbe0 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
2cbf0 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
2cc00 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2cc10 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(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 28 73 71  _value_text16(sq
2cc50 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
2cc60 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2cc70 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2cc80 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2cc90 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2cca0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2ccb0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
2ccc0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2ccd0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
2cce0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2ccf0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2cd00 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
2cd10 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
2cd20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2cd30 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
2cd40 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
2cd50 74 20 7b 46 31 36 32 31 30 7d 0a 2a 2a 0a 2a 2a  t {F16210}.**.**
2cd60 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
2cd70 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65  ion of aggregate
2cd80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
2cd90 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
2cda0 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61  to allocate.** a
2cdb0 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73   structure for s
2cdc0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
2cdd0 74 65 2e 20 20 0a 2a 2a 20 54 68 65 20 66 69 72  te.  .** The fir
2cde0 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
2cdf0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2ce00 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20  ntext() routine 
2ce10 69 73 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 20  is.** is called 
2ce20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2ce30 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69   aggregate, SQLi
2ce40 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79  te allocates nBy
2ce50 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  tes of memory.**
2ce60 20 7a 65 72 6f 73 20 74 68 61 74 20 6d 65 6d 6f   zeros that memo
2ce70 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
2ce80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e  a pointer to it.
2ce90 0a 2a 2a 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  .** On second an
2cea0 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
2ceb0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
2cec0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2ced0 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
2cee0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2cef0 74 69 6f 6e 20 69 6e 64 65 78 2c 20 74 68 65 20  tion index, the 
2cf00 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
2cf10 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  eturned..** The 
2cf20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
2cf30 2a 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  * of the aggrega
2cf40 74 65 20 63 61 6e 20 75 73 65 20 74 68 65 20 72  te can use the r
2cf50 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74  eturned buffer t
2cf60 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74  o accumulate dat
2cf70 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  a..**.** SQLite 
2cf80 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
2cf90 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  ees the allocate
2cfa0 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74 68  d buffer when th
2cfb0 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71  e aggregate.** q
2cfc0 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
2cfd0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2cfe0 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
2cff0 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
2d000 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  e .** [sqlite3_c
2d010 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
2d020 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
2d030 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
2d040 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
2d050 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f   the callback ro
2d060 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
2d070 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
2d080 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
2d090 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2d0a0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2d0b0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2d0c0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2d0d0 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
2d0e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2d0f0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
2d100 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2d110 2a 2a 20 7b 46 31 36 32 31 31 7d 20 54 68 65 20  ** {F16211} The 
2d120 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e  first invocation
2d130 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67 67   of [sqlite3_agg
2d140 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2d150 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20  ,N)] for.**     
2d160 20 20 20 20 20 61 20 70 61 72 74 69 63 75 6c 61       a particula
2d170 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 6e  r instance of an
2d180 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2d190 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74 69  ion (for a parti
2d1a0 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20 20  cular.**        
2d1b0 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61 75    context C) cau
2d1c0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61 6c  ses SQLite to al
2d1d0 6c 6f 63 61 74 69 6f 6e 20 4e 20 62 79 74 65 73  location N bytes
2d1e0 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20   of memory,.**  
2d1f0 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68 61          zero tha
2d200 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
2d210 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  turn a pointer t
2d220 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 0a  o the allocated.
2d230 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f  **          memo
2d240 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31  ry..**.** {F1621
2d250 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61  3} If a memory a
2d260 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
2d270 6f 63 63 75 72 73 20 64 75 72 69 6e 67 0a 2a 2a  occurs during.**
2d280 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2d290 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2d2a0 74 65 78 74 28 43 2c 4e 29 5d 20 74 68 65 6e 20  text(C,N)] then 
2d2b0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
2d2c0 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 46  urns 0..**.** {F
2d2d0 31 36 32 31 35 7d 20 53 65 63 6f 6e 64 20 61 6e  16215} Second an
2d2e0 64 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  d subsequent inv
2d2f0 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 20  ocations of.**  
2d300 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2d310 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2d320 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20 74 68 65  xt(C,N)] for the
2d330 20 73 61 6d 65 20 63 6f 6e 74 65 78 74 20 70 6f   same context po
2d340 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20 20 20 20  inter C.**      
2d350 20 20 20 20 69 67 6e 6f 72 65 20 74 68 65 20 4e      ignore the N
2d360 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
2d370 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20  eturn a pointer 
2d380 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  to the same.**  
2d390 20 20 20 20 20 20 20 20 62 6c 6f 63 6b 20 6f 66          block of
2d3a0 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
2d3b0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 69 6e   by the first in
2d3c0 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
2d3d0 7b 46 31 36 32 31 37 7d 20 54 68 65 20 6d 65 6d  {F16217} The mem
2d3e0 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ory allocated by
2d3f0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2d400 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2d410 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] is.**         
2d420 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
2d430 72 65 65 64 20 6f 6e 20 74 68 65 20 6e 65 78 74  reed on the next
2d440 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2d450 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 20 20  3_reset()].**   
2d460 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
2d470 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 66  e3_finalize()] f
2d480 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
2d490 20 73 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e 74   statement] cont
2d4a0 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  aining.**       
2d4b0 20 20 20 74 68 65 20 61 67 67 72 65 67 61 74 65     the aggregate
2d4c0 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69   function associ
2d4d0 61 74 65 64 20 77 69 74 68 20 63 6f 6e 74 65 78  ated with contex
2d4e0 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  t C..*/.void *sq
2d4f0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2d500 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
2d510 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
2d520 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
2d530 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
2d540 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20  a For Functions 
2d550 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F16240}.**.** T
2d560 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
2d570 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
2d580 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2d590 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
2d5a0 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
2d5b0 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
2d5c0 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
2d5d0 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
2d5e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2d5f0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
2d600 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
2d610 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2d620 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
2d630 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
2d640 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
2d650 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
2d660 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d   function. {END}
2d670 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2d680 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2d690 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2d6a0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2d6b0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
2d6c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2d6d0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2d6e0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2d6f0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 34 33  S:.**.** {F16243
2d700 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75  } The [sqlite3_u
2d710 73 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74  ser_data(C)] int
2d720 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2d730 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2d740 20 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74           P point
2d750 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  er from the [sql
2d760 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d770 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
2d780 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,S,L)].**       
2d790 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63     or [sqlite3_c
2d7a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2d7b0 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
2d7c0 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20  )] call that.** 
2d7d0 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
2d7e0 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  red the SQL func
2d7f0 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20  tion associated 
2d800 77 69 74 68 20 0a 2a 2a 20 20 20 20 20 20 20 20  with .**        
2d810 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65    [sqlite3_conte
2d820 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  xt] C..*/.void *
2d830 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2d840 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2d850 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2d860 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
2d870 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
2d880 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32 35 30 7d  nctions {F16250}
2d890 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2d8a0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2d8b0 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
2d8c0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2d8d0 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
2d8e0 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
2d8f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
2d900 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
2d910 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
2d920 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2d930 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
2d940 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2d950 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
2d960 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
2d970 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
2d980 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
2d990 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
2d9a0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ction..**.** INV
2d9b0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2d9c0 46 31 36 32 35 33 7d 20 54 68 65 20 5b 73 71 6c  F16253} The [sql
2d9d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2d9e0 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65 72  handle(C)] inter
2d9f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
2da00 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  opy of the.**   
2da10 20 20 20 20 20 20 20 44 20 70 6f 69 6e 74 65 72         D pointer
2da20 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
2da30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2da40 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53  on(D,X,N,E,P,F,S
2da50 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,L)].**         
2da60 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   or [sqlite3_cre
2da70 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44  ate_function16(D
2da80 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
2da90 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20   call that.**   
2daa0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
2dab0 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
2dac0 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  on associated wi
2dad0 74 68 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  th .**          
2dae0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2daf0 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ] C..*/.sqlite3 
2db00 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
2db10 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
2db20 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
2db30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2db40 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
2db50 79 20 44 61 74 61 20 7b 46 31 36 32 37 30 7d 0a  y Data {F16270}.
2db60 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
2db70 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
2db80 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
2db90 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2dba0 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
2dbb0 63 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20  ciate meta-data 
2dbc0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
2dbd0 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
2dbe0 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
2dbf0 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
2dc00 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
2dc10 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
2dc20 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
2dc30 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
2dc40 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
2dc50 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
2dc60 73 6f 63 69 61 74 65 64 20 6d 65 74 61 2d 64 61  sociated meta-da
2dc70 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
2dc80 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a  ved. This may.**
2dc90 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78   be used, for ex
2dca0 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20  ample, to add a 
2dcb0 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
2dcc0 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c  on matching scal
2dcd0 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ar.** function. 
2dce0 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
2dcf0 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
2dd00 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69  lar expression i
2dd10 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  s stored as.** m
2dd20 65 74 61 2d 64 61 74 61 20 61 73 73 6f 63 69 61  eta-data associa
2dd30 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ted with the SQL
2dd40 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
2dd50 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
2dd60 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65  ression.** patte
2dd70 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65  rn.  The compile
2dd80 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
2dd90 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
2dda0 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
2ddb0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
2ddc0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2ddd0 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f  on so that the o
2dde0 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20  riginal pattern 
2ddf0 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e  string.** does n
2de00 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65  ot need to be re
2de10 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68  compiled on each
2de20 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
2de30 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
2de40 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
2de50 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2de60 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2de70 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 61 73 73  meta-data.** ass
2de80 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
2de90 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2dea0 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
2deb0 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
2dec0 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
2ded0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2dee0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2def0 2e 0a 2a 2a 20 49 66 20 6e 6f 20 6d 65 74 61 2d  ..** If no meta-
2df00 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76  data has been ev
2df10 65 72 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  er been set for 
2df20 74 68 65 20 4e 74 68 0a 2a 2a 20 61 72 67 75 6d  the Nth.** argum
2df30 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ent of the funct
2df40 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63  ion, or if the c
2df50 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
2df60 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a  ction parameter.
2df70 2a 2a 20 68 61 73 20 63 68 61 6e 67 65 64 20 73  ** has changed s
2df80 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61  ince the meta-da
2df90 74 61 20 77 61 73 20 73 65 74 2c 20 74 68 65 6e  ta was set, then
2dfa0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
2dfb0 64 61 74 61 28 29 0a 2a 2a 20 72 65 74 75 72 6e  data().** return
2dfc0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2dfd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2dfe0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2dff0 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
2e000 73 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a  s the meta-data.
2e010 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
2e020 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
2e030 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 2d 64  er as the meta-d
2e040 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
2e050 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
2e060 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2e070 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2e080 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a  .  Subsequent.**
2e090 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2e0a0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
2e0b0 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69  might return thi
2e0c0 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61  s data, if it ha
2e0d0 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65  s.** not been de
2e0e0 73 74 72 6f 79 65 64 2e 20 0a 2a 2a 20 49 66 20  stroyed. .** If 
2e0f0 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  it is not NULL, 
2e100 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
2e110 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
2e120 72 20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67  r .** function g
2e130 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20  iven by the 4th 
2e140 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2e150 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2e160 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74  () on.** the met
2e170 61 2d 64 61 74 61 20 77 68 65 6e 20 74 68 65 20  a-data when the 
2e180 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
2e190 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
2e1a0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77   changes.** or w
2e1b0 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
2e1c0 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c  ement completes,
2e1d0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
2e1e0 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51   first..**.** SQ
2e1f0 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
2e200 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63  call the destruc
2e210 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74  tor and drop met
2e220 61 2d 64 61 74 61 20 6f 6e 0a 2a 2a 20 61 6e 79  a-data on.** any
2e230 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e   parameter of an
2e240 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e  y function at an
2e250 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c  y time.  The onl
2e260 79 20 67 75 61 72 61 6e 74 65 65 0a 2a 2a 20 69  y guarantee.** i
2e270 73 20 74 68 61 74 20 74 68 65 20 64 65 73 74 72  s that the destr
2e280 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61  uctor will be ca
2e290 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  lled before the 
2e2a0 6d 65 74 61 64 61 74 61 20 69 73 0a 2a 2a 20 64  metadata is.** d
2e2b0 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ropped..**.** In
2e2c0 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 2d   practice, meta-
2e2d0 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
2e2e0 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
2e2f0 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
2e300 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
2e310 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
2e320 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
2e330 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
2e340 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
2e350 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73  nd SQL variables
2e360 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2e370 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
2e380 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
2e390 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2e3a0 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
2e3b0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2e3c0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ng..**.** INVARI
2e3d0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
2e3e0 32 37 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  272} The [sqlite
2e3f0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_get_auxdata(C,
2e400 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
2e410 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
2e420 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 6d  **          to m
2e430 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
2e440 65 64 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  ed with the Nth 
2e450 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2e460 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL function.**
2e470 20 20 20 20 20 20 20 20 20 20 77 68 6f 73 65 20            whose 
2e480 63 6f 6e 74 65 78 74 20 69 73 20 43 2c 20 6f 72  context is C, or
2e490 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69   NULL if there i
2e4a0 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 61 73  s no metadata as
2e4b0 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20 20 20  sociated.**     
2e4c0 20 20 20 20 20 77 69 74 68 20 74 68 61 74 20 70       with that p
2e4d0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2e4e0 7b 46 31 36 32 37 34 7d 20 54 68 65 20 5b 73 71  {F16274} The [sq
2e4f0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2e500 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65  a(C,N,P,D)] inte
2e510 72 66 61 63 65 20 61 73 73 69 67 6e 73 20 61 20  rface assigns a 
2e520 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20  metadata.**     
2e530 20 20 20 20 20 70 6f 69 6e 74 65 72 20 50 20 74       pointer P t
2e540 6f 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65  o the Nth parame
2e550 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ter of the SQL f
2e560 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e  unction with con
2e570 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  text.**         
2e580 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37   C..**.** {F1627
2e590 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  6} SQLite will i
2e5a0 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2e5b0 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73 69  ctor D with a si
2e5c0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ngle argument.**
2e5d0 20 20 20 20 20 20 20 20 20 20 77 68 69 63 68 20            which 
2e5e0 69 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  is the metadata 
2e5f0 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77  pointer P follow
2e600 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ing a call to.**
2e610 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2e620 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
2e630 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 51  ,N,P,D)] when SQ
2e640 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68  Lite ceases to h
2e650 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  old.**          
2e660 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a  the metadata..**
2e670 0a 2a 2a 20 7b 46 31 36 32 37 37 7d 20 53 51 4c  .** {F16277} SQL
2e680 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f  ite ceases to ho
2e690 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  ld metadata for 
2e6a0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
2e6b0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
2e6c0 20 20 20 20 20 20 77 68 65 6e 20 74 68 65 20 76        when the v
2e6d0 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61 72  alue of that par
2e6e0 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e 0a  ameter changes..
2e6f0 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 38 7d 20 57  **.** {F16278} W
2e700 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  hen [sqlite3_set
2e710 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44  _auxdata(C,N,P,D
2e720 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  )] is invoked, t
2e730 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
2e740 20 20 20 20 20 20 20 20 20 20 69 73 20 63 61 6c            is cal
2e750 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69 6f  led for any prio
2e760 72 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  r metadata assoc
2e770 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73  iated with the s
2e780 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ame function.** 
2e790 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74           context
2e7a0 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72   C and parameter
2e7b0 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37   N..**.** {F1627
2e7c0 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63  9} SQLite will c
2e7d0 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73 20  all destructors 
2e7e0 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74 61  for any metadata
2e7f0 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a   it is holding.*
2e800 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61 20  *          in a 
2e810 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65 70  particular [prep
2e820 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2e830 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a  S when either.**
2e840 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2e850 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 20  e3_reset(S)] or 
2e860 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2e870 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  e(S)] is called.
2e880 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2e890 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
2e8a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2e8b0 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c  int N);.void sql
2e8c0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2e8d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2e8e0 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c  *, int N, void*,
2e8f0 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29   void (*)(void*)
2e900 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
2e910 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44  REF: Constants D
2e920 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20  efining Special 
2e930 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76  Destructor Behav
2e940 69 6f 72 20 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a  ior {F10280}.**.
2e950 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
2e960 63 69 61 6c 20 76 61 6c 75 65 20 66 6f 72 20 74  cial value for t
2e970 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
2e980 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
2e990 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
2e9a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
2e9b0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
2e9c0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
2e9d0 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72  ].  If the destr
2e9e0 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
2e9f0 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
2ea00 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
2ea10 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
2ea20 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
2ea30 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
2ea40 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
2ea50 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
2ea60 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
2ea70 54 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  The .** SQLITE_T
2ea80 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
2ea90 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
2eaa0 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
2eab0 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
2eac0 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
2ead0 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
2eae0 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
2eaf0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2eb00 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
2eb10 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
2eb20 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
2eb30 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
2eb40 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
2eb50 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
2eb60 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
2eb70 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63  pilers.  See tic
2eb80 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79  ket #2191..*/.ty
2eb90 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
2eba0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
2ebb0 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
2ebc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
2ebd0 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
2ebe0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
2ebf0 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
2ec00 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
2ec10 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
2ec20 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
2ec30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ec40 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
2ec50 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
2ec60 63 74 69 6f 6e 20 7b 46 31 36 34 30 30 7d 0a 2a  ction {F16400}.*
2ec70 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2ec80 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
2ec90 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
2eca0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
2ecb0 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
2ecc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
2ecd0 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
2ece0 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
2ecf0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2ed00 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2ed10 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2ed20 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
2ed30 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
2ed40 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
2ed50 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
2ed60 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
2ed70 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69   .** [sqlite3_bi
2ed80 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
2ed90 33 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79  3_bind_*] family
2eda0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 20 75 73   of functions us
2edb0 65 64 0a 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61  ed.** to bind va
2edc0 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
2edd0 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
2ede0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
2edf0 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 0a  ** Refer to the.
2ee00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2ee10 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2ee20 62 69 6e 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61  bind_* documenta
2ee30 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64  tion] for.** add
2ee40 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
2ee50 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
2ee60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2ee70 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
2ee80 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
2ee90 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
2eea0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
2eeb0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
2eec0 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
2eed0 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
2eee0 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
2eef0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
2ef00 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
2ef10 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
2ef20 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
2ef30 61 72 61 6d 65 74 65 72 2e 20 0a 2a 2a 20 54 68  arameter. .** Th
2ef40 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2ef50 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
2ef60 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
2ef70 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2ef80 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2ef90 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2efa0 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
2efb0 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
2efc0 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
2efd0 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
2efe0 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
2eff0 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
2f000 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  meter..**.** The
2f010 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f020 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
2f030 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
2f040 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
2f050 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2f060 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2f070 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
2f080 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
2f090 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
2f0a0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2f0b0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2f0c0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
2f0d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f0e0 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
2f0f0 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
2f100 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
2f110 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
2f120 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
2f130 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
2f140 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
2f150 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
2f160 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
2f170 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f180 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
2f190 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2f1a0 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
2f1b0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
2f1c0 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e  sage.  SQLite in
2f1d0 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
2f1e0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
2f1f0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
2f200 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2f210 20 61 73 20 55 54 46 38 2e 20 53 51 4c 69 74 65   as UTF8. SQLite
2f220 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
2f230 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
2f240 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f250 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 31 36  ror16() as UTF16
2f260 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
2f270 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68  te order.  If th
2f280 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2f290 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
2f2a0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
2f2b0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2f2c0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
2f2d0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
2f2e0 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
2f2f0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2f300 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
2f310 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
2f320 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
2f330 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70  * If the third p
2f340 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2f350 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f360 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2f370 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2f380 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
2f390 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
2f3a0 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
2f3b0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
2f3c0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
2f3d0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
2f3e0 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
2f3f0 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  age..** The sqli
2f400 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f410 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
2f420 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
2f430 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
2f440 20 61 20 63 6f 70 79 20 70 72 69 76 61 74 65 20   a copy private 
2f450 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
2f460 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
2f470 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
2f480 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
2f490 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
2f4a0 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
2f4b0 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
2f4c0 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
2f4d0 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
2f4e0 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73  t harm..** The s
2f4f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f500 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
2f510 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
2f520 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
2f530 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
2f540 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
2f550 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
2f560 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61  nction.  By defa
2f570 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
2f580 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
2f590 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65  _ERROR.  A subse
2f5a0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
2f5b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f5c0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
2f5d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2f5e0 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
2f5f0 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
2f600 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
2f610 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2f620 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ult_toobig() int
2f630 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
2f640 4c 69 74 65 0a 2a 2a 20 74 6f 20 74 68 72 6f 77  Lite.** to throw
2f650 20 61 6e 20 65 72 72 6f 72 20 69 6e 64 69 63 61   an error indica
2f660 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
2f670 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
2f680 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65 70 72   long.** to repr
2f690 65 73 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  esent.  The sqli
2f6a0 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d  te3_result_nomem
2f6b0 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
2f6c0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
2f6d0 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
2f6e0 69 6f 6e 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ion indicating t
2f6f0 68 61 74 20 74 68 65 20 61 0a 2a 2a 20 6d 65 6d  hat the a.** mem
2f700 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
2f710 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ailed..**.** The
2f720 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f730 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
2f740 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
2f750 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
2f760 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f770 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2f780 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
2f790 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2f7a0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
2f7b0 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
2f7c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2f7d0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
2f7e0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2f7f0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2f800 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
2f810 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2f820 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
2f830 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2f840 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
2f850 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
2f860 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2f870 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2f880 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
2f890 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2f8a0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2f8b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2f8c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2f8d0 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
2f8e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2f8f0 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
2f900 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2f910 74 31 36 28 29 2c 20 0a 2a 2a 20 73 71 6c 69 74  t16(), .** sqlit
2f920 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2f930 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
2f940 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
2f950 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
2f960 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
2f970 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
2f980 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2f990 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2f9a0 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
2f9b0 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
2f9c0 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
2f9d0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
2f9e0 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
2f9f0 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
2fa00 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
2fa10 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
2fa20 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74  tively..** SQLit
2fa30 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
2fa40 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
2fa50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
2fa60 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
2fa70 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
2fa80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2fa90 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
2faa0 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
2fab0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2fac0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2fad0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2fae0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2faf0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
2fb00 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
2fb10 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2fb20 65 72 20 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  er .** through t
2fb30 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
2fb40 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74  aracter..** If t
2fb50 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2fb60 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2fb70 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2fb80 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
2fb90 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
2fba0 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
2fbb0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
2fbc0 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
2fbd0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
2fbe0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
2fbf0 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
2fc00 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2fc10 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
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 0a 2a 2a 20 6f 72 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 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
2fc90 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
2fca0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
2fcb0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
2fcc0 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
2fcd0 74 68 65 20 74 65 78 74 20 6f 72 20 62 6c 6f 62  the text or blob
2fce0 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
2fcf0 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
2fd00 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
2fd10 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
2fd20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2fd30 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2fd40 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2fd50 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
2fd60 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
2fd70 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
2fd80 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
2fd90 43 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  C, then.** SQLit
2fda0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
2fdb0 68 65 20 74 65 78 74 20 6f 72 20 62 6c 6f 62 20  he text or blob 
2fdc0 72 65 73 75 6c 74 20 69 73 20 63 6f 6e 73 74 61  result is consta
2fdd0 6e 74 20 73 70 61 63 65 20 61 6e 64 0a 2a 2a 20  nt space and.** 
2fde0 64 6f 65 73 20 6e 6f 74 20 63 6f 70 79 20 74 68  does not copy th
2fdf0 65 20 73 70 61 63 65 20 6f 72 20 63 61 6c 6c 20  e space or call 
2fe00 61 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65  a destructor whe
2fe10 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
2fe20 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
2fe30 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68  result..** If th
2fe40 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2fe50 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2fe60 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2fe70 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
2fe80 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2fe90 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
2fea0 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
2feb0 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
2fec0 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
2fed0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
2fee0 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
2fef0 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
2ff00 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2ff10 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
2ff20 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
2ff30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2ff40 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
2ff50 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2ff60 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2ff70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2ff80 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2ff90 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a  be a copy the.**
2ffa0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2ffb0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2ffc0 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
2ffd0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2ffe0 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  er.  The.** sqli
2fff0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
30000 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
30010 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
30020 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
30030 0a 2a 2a 20 73 6f 20 74 68 61 74 20 5b 73 71 6c  .** so that [sql
30040 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
30050 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
30060 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
30070 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
30080 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
30090 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
300a0 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
300b0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b  out harm..** A [
300c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
300d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
300e0 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
300f0 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
30100 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
30110 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30120 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
30130 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
30140 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
30150 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
30160 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
30170 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
30180 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
30190 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
301a0 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
301b0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
301c0 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
301d0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
301e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
301f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
30200 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
30210 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
30220 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
30230 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
30240 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  efined..**.** IN
30250 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
30260 7b 46 31 36 34 30 33 7d 20 54 68 65 20 64 65 66  {F16403} The def
30270 61 75 6c 74 20 72 65 74 75 72 6e 20 76 61 6c 75  ault return valu
30280 65 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c 20 66  e from any SQL f
30290 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e  unction is NULL.
302a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 36 7d 20  .**.** {F16406} 
302b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
302c0 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44  ult_blob(C,V,N,D
302d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
302e0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
302f0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
30300 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
30310 74 6f 20 62 65 20 61 20 62 6c 6f 62 20 74 68 61  to be a blob tha
30320 74 20 69 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20  t is N bytes.** 
30330 20 20 20 20 20 20 20 20 20 69 6e 20 6c 65 6e 67           in leng
30340 74 68 20 61 6e 64 20 77 69 74 68 20 63 6f 6e 74  th and with cont
30350 65 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ent pointed to b
30360 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  y V..**.** {F164
30370 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
30380 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 43  _result_double(C
30390 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,V)] interface c
303a0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
303b0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
303c0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
303d0 43 20 74 6f 20 62 65 20 74 68 65 20 66 6c 6f 61  C to be the floa
303e0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
303f0 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31   V..**.** {F1641
30400 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
30410 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 43 2c 56  result_error(C,V
30420 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
30430 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72  hanges the retur
30440 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  n.**          va
30450 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
30460 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
30470 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
30480 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
30490 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
304a0 61 6e 64 20 61 20 55 54 46 38 20 65 72 72 6f 72  and a UTF8 error
304b0 20 6d 65 73 73 61 67 65 20 63 6f 70 69 65 64 20   message copied 
304c0 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65  from V up to the
304d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 72  .**          fir
304e0 73 74 20 7a 65 72 6f 20 62 79 74 65 20 6f 72 20  st zero byte or 
304f0 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72  until N bytes ar
30500 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70  e read if N is p
30510 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  ositive..**.** {
30520 46 31 36 34 31 35 7d 20 54 68 65 20 5b 73 71 6c  F16415} The [sql
30530 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30540 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65  r16(C,V,N)] inte
30550 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
30560 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
30570 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75       value of fu
30580 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
30590 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
305a0 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
305b0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
305c0 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46  ERROR] and a UTF
305d0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
305e0 72 64 65 72 20 65 72 72 6f 72 20 6d 65 73 73 61  rder error messa
305f0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ge.**          c
30600 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20  opied from V up 
30610 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
30620 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20  o terminator or 
30630 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a  until N bytes.**
30640 20 20 20 20 20 20 20 20 20 20 61 72 65 20 72 65            are re
30650 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  ad if N is posit
30660 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ive..**.** {F164
30670 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  18} The [sqlite3
30680 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
30690 6f 62 69 67 28 43 29 5d 20 69 6e 74 65 72 66 61  obig(C)] interfa
306a0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
306b0 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
306c0 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66    value of the f
306d0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
306e0 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
306f0 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  h error code.** 
30700 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
30710 5f 54 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20  _TOOBIG] and an 
30720 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
30730 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
30740 20 7b 46 31 36 34 32 31 7d 20 54 68 65 20 5b 73   {F16421} The [s
30750 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30760 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e  ror_nomem(C)] in
30770 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
30780 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
30790 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
307a0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74  the function C t
307b0 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
307c0 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
307d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
307e0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64  QLITE_NOMEM] and
307f0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
30800 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
30810 2a 0a 2a 2a 20 7b 46 31 36 34 32 34 7d 20 54 68  *.** {F16424} Th
30820 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
30830 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45  t_error_code(C,E
30840 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
30850 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a  nges the return.
30860 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
30870 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
30880 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
30890 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
308a0 72 20 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20  r code E..**    
308b0 20 20 20 20 20 20 54 68 65 20 65 72 72 6f 72 20        The error 
308c0 6d 65 73 73 61 67 65 20 74 65 78 74 20 69 73 20  message text is 
308d0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  unchanged..**.**
308e0 20 7b 46 31 36 34 32 37 7d 20 54 68 65 20 5b 73   {F16427} The [s
308f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
30900 74 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63  t(C,V)] interfac
30910 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
30920 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
30930 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
30940 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 33  on C to be the 3
30950 32 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 61  2-bit integer va
30960 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  lue V..**.** {F1
30970 36 34 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74  6430} The [sqlit
30980 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
30990 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,V)] interface 
309a0 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
309b0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
309c0 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
309d0 20 43 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d   C to be the 64-
309e0 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75  bit integer valu
309f0 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  e V..**.** {F164
30a00 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  33} The [sqlite3
30a10 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d  _result_null(C)]
30a20 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
30a30 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
30a40 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
30a50 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
30a60 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
30a70 7b 46 31 36 34 33 36 7d 20 54 68 65 20 5b 73 71  {F16436} The [sq
30a80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
30a90 74 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65  t(C,V,N,D)] inte
30aa0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
30ab0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
30ac0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
30ad0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
30ae0 68 65 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a  he UTF8 string.*
30af0 2a 20 20 20 20 20 20 20 20 20 20 56 20 75 70 20  *          V up 
30b00 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
30b10 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  o if N is negati
30b20 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ve.**          o
30b30 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
30b40 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73  tes of V if N is
30b50 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
30b60 2a 0a 2a 2a 20 7b 46 31 36 34 33 39 7d 20 54 68  *.** {F16439} Th
30b70 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
30b80 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
30b90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
30ba0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
30bb0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
30bc0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
30bd0 74 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 20  to be the UTF16 
30be0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
30bf0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  r.**          st
30c00 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
30c10 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
30c20 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
30c30 6e 65 67 61 74 69 76 65 20 6f 72 20 74 68 65 20  negative or the 
30c40 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
30c50 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
30c60 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
30c70 46 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71 6c  F16442} The [sql
30c80 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
30c90 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16be(C,V,N,D)] i
30ca0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
30cb0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30cc0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
30cd0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
30ce0 65 20 74 68 65 20 55 54 46 31 36 20 62 69 67 2d  e the UTF16 big-
30cf0 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
30d00 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74     string V up t
30d10 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
30d20 20 69 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20 20   if N is.**     
30d30 20 20 20 20 20 69 73 20 6e 65 67 61 74 69 76 65       is negative
30d40 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20   or the first N 
30d50 62 79 74 65 73 20 6f 72 20 56 20 69 66 20 4e 20  bytes or V if N 
30d60 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
30d70 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 35 7d 20  .**.** {F16445} 
30d80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
30d90 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56  ult_text16le(C,V
30da0 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
30db0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
30dc0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
30dd0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
30de0 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
30df0 46 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  F16 little-endia
30e00 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
30e10 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
30e20 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
30e30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
30e40 6e 65 67 61 74 69 76 65 20 6f 72 20 74 68 65 20  negative or the 
30e50 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
30e60 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
30e70 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
30e80 46 31 36 34 34 38 7d 20 54 68 65 20 5b 73 71 6c  F16448} The [sql
30e90 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
30ea0 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63  e(C,V)] interfac
30eb0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
30ec0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
30ed0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
30ee0 6f 6e 20 43 20 74 6f 20 62 65 20 5b 75 6e 70 72  on C to be [unpr
30ef0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30f00 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20  value].**       
30f10 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a     object V..**.
30f20 2a 2a 20 7b 46 31 36 34 35 31 7d 20 54 68 65 20  ** {F16451} The 
30f30 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
30f40 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69  zeroblob(C,N)] i
30f50 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
30f60 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30f70 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
30f80 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
30f90 65 20 61 6e 20 4e 2d 62 79 74 65 20 62 6c 6f 62  e an N-byte blob
30fa0 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a   of all zeros..*
30fb0 2a 0a 2a 2a 20 7b 46 31 36 34 35 34 7d 20 54 68  *.** {F16454} Th
30fc0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
30fd0 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b  t_error()] and [
30fe0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30ff0 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20  rror16()].**    
31000 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
31010 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
31020 74 68 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73  their error mess
31030 61 67 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f  age strings befo
31040 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  re.**          r
31050 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
31060 7b 46 31 36 34 35 37 7d 20 49 66 20 74 68 65 20  {F16457} If the 
31070 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72  D destructor par
31080 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
31090 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43  e3_result_blob(C
310a0 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
310b0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
310c0 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
310d0 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72  ,D)], [sqlite3_r
310e0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56  esult_text16(C,V
310f0 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
31100 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
31110 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56  ult_text16be(C,V
31120 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,N,D)], or.**   
31130 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
31140 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
31150 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65  C,V,N,D)] is the
31160 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54   constant [SQLIT
31170 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20  E_STATIC].**    
31180 20 20 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65        then no de
31190 73 74 72 75 63 74 6f 72 20 69 73 20 65 76 65 72  structor is ever
311a0 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70   called on the p
311b0 6f 69 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c  ointer V and SQL
311c0 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ite.**          
311d0 61 73 73 75 6d 65 73 20 74 68 61 74 20 56 20 69  assumes that V i
311e0 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a  s immutable..**.
311f0 2a 2a 20 7b 46 31 36 34 36 30 7d 20 49 66 20 74  ** {F16460} If t
31200 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
31210 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
31220 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
31230 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
31240 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
31250 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
31260 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
31270 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
31280 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
31290 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
312a0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
312b0 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
312c0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
312d0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
312e0 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
312f0 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20  the constant.** 
31300 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
31310 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e  _TRANSIENT] then
31320 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
31330 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
31340 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
31350 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64  content of V and
31360 20 72 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70   retains the cop
31370 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 33  y..**.** {F16463
31380 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
31390 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
313a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
313b0 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
313c0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
313d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
313e0 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
313f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31400 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
31410 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
31420 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31430 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
31440 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
31450 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
31460 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
31470 29 5d 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65  )] is some value
31480 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
31490 20 20 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73          the cons
314a0 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54  tants [SQLITE_ST
314b0 41 54 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATIC] and [SQLIT
314c0 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65  E_TRANSIENT] the
314d0 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  n .**          S
314e0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
314f0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
31500 20 44 20 77 69 74 68 20 56 20 61 73 20 69 74 73   D with V as its
31510 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a   only argument.*
31520 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20  *          when 
31530 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
31540 77 69 74 68 20 74 68 65 20 56 20 76 61 6c 75 65  with the V value
31550 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
31560 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
31570 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31580 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
31590 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
315a0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
315b0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
315c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
315d0 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
315e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
315f0 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
31600 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
31610 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
31620 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31630 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
31640 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
31650 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
31660 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31670 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
31680 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
31690 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
316a0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
316b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
316c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
316d0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
316e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
316f0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
31700 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
31710 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
31720 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
31730 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
31740 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31750 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
31760 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
31770 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
31780 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
31790 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
317a0 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
317b0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
317c0 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
317d0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
317e0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
317f0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
31800 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
31810 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
31820 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
31830 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
31840 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
31850 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
31860 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
31870 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
31880 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
31890 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
318a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
318b0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
318c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
318d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
318e0 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
318f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
31900 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
31910 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31920 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
31930 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
31940 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31950 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
31960 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
31970 65 73 20 7b 46 31 36 36 30 30 7d 0a 2a 2a 0a 2a  es {F16600}.**.*
31980 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
31990 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  s are used to ad
319a0 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  d new collation 
319b0 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65  sequences to the
319c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68  .** [sqlite3*] h
319d0 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65 64 20  andle specified 
319e0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
319f0 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68  ument. .**.** Th
31a00 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65  e name of the ne
31a10 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
31a20 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65  ence is specifie
31a30 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72  d as a UTF-8 str
31a40 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
31a50 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
31a60 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
31a70 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
31a80 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
31a90 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66   UTF-16 string f
31aa0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
31ab0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
31ac0 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a   In all cases.**
31ad0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73   the name is pas
31ae0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
31af0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
31b00 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ent..**.** The t
31b10 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61  hird argument ma
31b20 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  y be one of the 
31b30 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
31b40 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
31b50 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20  ITE_UTF16LE] or 
31b60 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
31b70 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  , indicating tha
31b80 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c  t the user-suppl
31b90 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65  ied.** routine e
31ba0 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73  xpects to be pas
31bb0 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  sed pointers to 
31bc0 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20  strings encoded 
31bd0 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20  using UTF-8,.** 
31be0 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e  UTF-16 little-en
31bf0 64 69 61 6e 20 6f 72 20 55 54 46 2d 31 36 20 62  dian or UTF-16 b
31c00 69 67 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  ig-endian respec
31c10 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74  tively. The.** t
31c20 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69  hird argument mi
31c30 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c  ght also be [SQL
31c40 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
31c50 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  D] to indicate t
31c60 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69  hat.** the routi
31c70 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ne expects point
31c80 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f  ers to 16-bit wo
31c90 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e  rd aligned strin
31ca0 67 73 0a 2a 2a 20 6f 66 20 55 54 46 31 36 20 69  gs.** of UTF16 i
31cb0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
31cc0 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e order of the h
31cd0 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a  ost computer..**
31ce0 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
31cf0 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69   the user suppli
31d00 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  ed routine must 
31d10 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
31d20 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65   fifth.** argume
31d30 6e 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55  nt.  If it is NU
31d40 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  LL, this is the 
31d50 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67  same as deleting
31d60 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
31d70 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74  * sequence (so t
31d80 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f  hat SQLite canno
31d90 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72  t call it anymor
31da0 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65  e)..** Each time
31db0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31dc0 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 66 75 6e  .** supplied fun
31dd0 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
31de0 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61  , it is passed a
31df0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
31e00 64 2a 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20  d* passed as.** 
31e10 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
31e20 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
31e30 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
31e40 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
31e50 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
31e60 31 36 28 29 20 61 73 20 69 74 73 20 66 69 72 73  16() as its firs
31e70 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  t parameter..**.
31e80 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
31e90 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
31ea0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  e application-su
31eb0 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61  pplied routine a
31ec0 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a  re two strings,.
31ed0 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e  ** each represen
31ee0 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68  ted by a (length
31ef0 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64  , data) pair and
31f00 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20   encoded in the 
31f10 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74  encoding.** that
31f20 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74   was passed as t
31f30 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
31f40 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  t when the colla
31f50 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61  tion sequence wa
31f60 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e  s.** registered.
31f70 20 7b 45 4e 44 7d 20 54 68 65 20 61 70 70 6c 69   {END} The appli
31f80 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63  cation defined c
31f90 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  ollation routine
31fa0 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
31fb0 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  n negative, zero
31fc0 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 0a   or positive if.
31fd0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 73 74 72  ** the first str
31fe0 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
31ff0 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
32000 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
32010 73 65 63 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e 67  second.** string
32020 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20  . i.e. (STRING1 
32030 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a  - STRING2)..**.*
32040 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72  * The sqlite3_cr
32050 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
32060 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
32070 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32080 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63  llation().** exc
32090 65 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65  ept that it take
320a0 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d  s an extra argum
320b0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64  ent which is a d
320c0 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a  estructor for.**
320d0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20   the collation. 
320e0 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
320f0 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  is called when t
32100 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a  he collation is.
32110 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64  ** destroyed and
32120 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70   is passed a cop
32130 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  y of the fourth 
32140 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20  parameter void* 
32150 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68  pointer.** of th
32160 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
32170 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e  _collation_v2().
32180 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61  .** Collations a
32190 72 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65  re destroyed whe
321a0 6e 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 6f 76  n.** they are ov
321b0 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
321c0 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63  r calls to the c
321d0 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
321e0 6e 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f  n functions.** o
321f0 72 20 77 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  r when the [sqli
32200 74 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68  te3*] database h
32210 61 6e 64 6c 65 20 69 73 20 63 6c 6f 73 65 64 20  andle is closed 
32220 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
32230 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  lose()]..**.** I
32240 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
32250 20 7b 46 31 36 36 30 33 7d 20 41 20 73 75 63 63   {F16603} A succ
32260 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74  essful call to t
32270 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
32280 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
32290 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
322a0 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66  E,P,F,D)] interf
322b0 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ace.**          
322c0 72 65 67 69 73 74 65 72 73 20 66 75 6e 63 74 69  registers functi
322d0 6f 6e 20 46 20 61 73 20 74 68 65 20 63 6f 6d 70  on F as the comp
322e0 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  arison function 
322f0 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20  used to.**      
32300 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f      implement co
32310 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 5b 64 61  llation X on [da
32320 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32330 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20 20  n] B for.**     
32340 20 20 20 20 20 64 61 74 61 62 61 73 65 73 20 68       databases h
32350 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 45  aving encoding E
32360 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 34 7d  ..**.** {F16604}
32370 20 53 51 4c 69 74 65 20 75 6e 64 65 72 73 74 61   SQLite understa
32380 6e 64 73 20 74 68 65 20 58 20 70 61 72 61 6d 65  nds the X parame
32390 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
323a0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
323b0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
323c0 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61 73  B,X,E,P,F,D)] as
323d0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
323e0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55  ed.**          U
323f0 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 20 77  TF-8 string in w
32400 68 69 63 68 20 63 61 73 65 20 69 73 20 69 67 6e  hich case is ign
32410 6f 72 65 64 20 66 6f 72 20 41 53 43 49 49 20 63  ored for ASCII c
32420 68 61 72 61 63 74 65 72 73 20 61 6e 64 0a 2a 2a  haracters and.**
32430 20 20 20 20 20 20 20 20 20 20 69 73 20 73 69 67            is sig
32440 6e 69 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f 6e  nificant for non
32450 2d 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72  -ASCII character
32460 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 36  s..**.** {F16606
32470 7d 20 53 75 63 63 65 73 73 69 76 65 20 63 61 6c  } Successive cal
32480 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ls to [sqlite3_c
32490 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
324a0 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
324b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
324c0 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  h the same value
324d0 73 20 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64 20  s for B, X, and 
324e0 45 2c 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f  E, override prio
324f0 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20  r values.**     
32500 20 20 20 20 20 6f 66 20 50 2c 20 46 2c 20 61 6e       of P, F, an
32510 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  d D..**.** {F166
32520 30 39 7d 20 54 68 65 20 64 65 73 74 72 75 63 74  09} The destruct
32530 6f 72 20 44 20 69 6e 20 5b 73 71 6c 69 74 65 33  or D in [sqlite3
32540 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
32550 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
32560 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
32570 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
32580 69 74 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  it is called wit
32590 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
325a0 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
325b0 20 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63    collating func
325c0 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20  tion is dropped 
325d0 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  by SQLite..**.**
325e0 20 7b 46 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c   {F16612} A coll
325f0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
32600 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 69  s dropped when i
32610 74 20 69 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e  t is overloaded.
32620 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 35 7d 20  .**.** {F16615} 
32630 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  A collating func
32640 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20  tion is dropped 
32650 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
32660 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
32670 20 20 20 20 20 20 20 20 20 69 73 20 63 6c 6f 73           is clos
32680 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
32690 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
326a0 2a 20 7b 46 31 36 36 31 38 7d 20 54 68 65 20 70  * {F16618} The p
326b0 6f 69 6e 74 65 72 20 50 20 69 6e 20 5b 73 71 6c  ointer P in [sql
326c0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
326d0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
326e0 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
326f0 20 20 20 69 73 20 70 61 73 73 65 64 20 74 68 72     is passed thr
32700 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
32710 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
32720 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a  he comparison.**
32730 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
32740 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 73 75 62  on F for all sub
32750 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
32760 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20  ons of F..**.** 
32770 7b 46 31 36 36 32 31 7d 20 41 20 63 61 6c 6c 20  {F16621} A call 
32780 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
32790 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58  te_collation(B,X
327a0 2c 45 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 63  ,E,P,F)] is exac
327b0 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tly.**          
327c0 74 68 65 20 73 61 6d 65 20 61 73 20 61 20 63 61  the same as a ca
327d0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
327e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
327f0 76 32 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20  v2()] with.**   
32800 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
32810 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 61  parameters and a
32820 20 4e 55 4c 4c 20 64 65 73 74 72 75 63 74 6f 72   NULL destructor
32830 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 34 7d  ..**.** {F16624}
32840 20 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71   Following a [sq
32850 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
32860 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c  lation_v2(B,X,E,
32870 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  P,F,D)],.**     
32880 20 20 20 20 20 53 51 4c 69 74 65 20 75 73 65 73       SQLite uses
32890 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20   the comparison 
328a0 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61  function F for a
328b0 6c 6c 20 74 65 78 74 20 63 6f 6d 70 61 72 69 73  ll text comparis
328c0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
328d0 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 5b 64 61  perations on [da
328e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
328f0 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20 76 61 6c  n] B on text val
32900 75 65 73 20 74 68 61 74 0a 2a 2a 20 20 20 20 20  ues that.**     
32910 20 20 20 20 20 75 73 65 20 74 68 65 20 63 6f 6c       use the col
32920 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20  lating sequence 
32930 6e 61 6d 65 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 46  name X..**.** {F
32940 31 36 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69  16627} The [sqli
32950 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32960 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46  tion16(B,X,E,P,F
32970 29 5d 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d  )] works the sam
32980 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  e.**          as
32990 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
329a0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45  _collation(B,X,E
329b0 2c 50 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68  ,P,F)] except th
329c0 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  at the.**       
329d0 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d     collation nam
329e0 65 20 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f  e X is understoo
329f0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  d as UTF-16 in n
32a00 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
32a10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73  .**          ins
32a20 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a  tead of UTF-8..*
32a30 2a 0a 2a 2a 20 7b 46 31 36 36 33 30 7d 20 57 68  *.** {F16630} Wh
32a40 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70  en multiple comp
32a50 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  arison functions
32a60 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66   are available f
32a70 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  or the same.**  
32a80 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
32a90 67 20 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69  g sequence, SQLi
32aa0 74 65 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f  te chooses the o
32ab0 6e 65 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e  ne whose text en
32ac0 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  coding.**       
32ad0 20 20 20 72 65 71 75 69 72 65 73 20 74 68 65 20     requires the 
32ae0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
32af0 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
32b00 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20  the default.**  
32b10 20 20 20 20 20 20 20 20 74 65 78 74 20 65 6e 63          text enc
32b20 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  oding of the dat
32b30 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  abase..*/.int sq
32b40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
32b50 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
32b60 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
32b70 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
32b80 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
32b90 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
32ba0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
32bb0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
32bc0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
32bd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
32be0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
32bf0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
32c00 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
32c10 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
32c20 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
32c30 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
32c40 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
32c50 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
32c60 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
32c70 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
32c80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
32c90 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
32ca0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
32cb0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
32cc0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
32cd0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
32ce0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
32cf0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
32d00 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
32d10 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
32d20 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
32d30 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
32d40 6c 62 61 63 6b 73 20 7b 46 31 36 37 30 30 7d 0a  lbacks {F16700}.
32d50 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68  **.** To avoid h
32d60 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65  aving to registe
32d70 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20  r all collation 
32d80 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65  sequences before
32d90 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
32da0 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69  an be used, a si
32db0 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ngle callback fu
32dc0 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
32dd0 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68  gistered with th
32de0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61  e.** database ha
32df0 6e 64 6c 65 20 74 6f 20 62 65 20 63 61 6c 6c 65  ndle to be calle
32e00 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
32e10 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
32e20 6e 20 73 65 71 75 65 6e 63 65 20 69 73 0a 2a 2a  n sequence is.**
32e30 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
32e40 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   If the function
32e50 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
32e60 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
32e70 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
32e80 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
32e90 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
32ea0 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
32eb0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
32ec0 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
32ed0 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
32ee0 6e 20 55 54 46 2d 38 2e 20 7b 46 31 36 37 30 33  n UTF-8. {F16703
32ef0 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  } If sqlite3_col
32f00 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
32f10 29 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 6e  ) is used, the n
32f20 61 6d 65 73 0a 2a 2a 20 61 72 65 20 70 61 73 73  ames.** are pass
32f30 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
32f40 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62  machine native b
32f50 79 74 65 20 6f 72 64 65 72 2e 20 41 20 63 61 6c  yte order. A cal
32f60 6c 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66  l to either.** f
32f70 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
32f80 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61   any existing ca
32f90 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68  llback..**.** Wh
32fa0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
32fb0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
32fc0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
32fd0 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
32fe0 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
32ff0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
33000 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
33010 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
33020 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
33030 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
33040 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
33050 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
33060 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20 20 54 68 65  .** handle.  The
33070 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
33080 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
33090 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
330a0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
330b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
330c0 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
330d0 65 20 6d 6f 73 74 0a 2a 2a 20 64 65 73 69 72 61  e most.** desira
330e0 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
330f0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
33100 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
33110 69 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 75  ired..** The fou
33120 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
33130 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
33140 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
33150 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
33160 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
33170 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
33180 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
33190 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
331a0 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
331b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
331c0 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
331d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
331e0 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
331f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33200 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
33210 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
33220 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 32  S:.**.** {F16702
33230 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
33240 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
33250 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
33260 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20  (D,P,F)].**     
33270 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
33280 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
33290 64 31 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73  d16(D,P,F)] caus
332a0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  es.**          t
332b0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
332c0 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e  nection] D to in
332d0 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20  voke callback F 
332e0 77 69 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20  with first.**   
332f0 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
33300 20 50 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e   P whenever it n
33310 65 65 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f  eeds a compariso
33320 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61  n function for a
33330 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
33340 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20  lating sequence 
33350 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74  that it does not
33360 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a   know about..**.
33370 2a 2a 20 7b 46 31 36 37 30 34 7d 20 45 61 63 68  ** {F16704} Each
33380 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
33390 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
333a0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
333b0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
333c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
333d0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f  on_needed16()] o
333e0 76 65 72 72 69 64 65 73 20 74 68 65 20 63 61 6c  verrides the cal
333f0 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72 65 64  lback registered
33400 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20  .**          on 
33410 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
33420 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62  se connection] b
33430 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f  y prior calls to
33440 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
33450 20 20 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a      interface..*
33460 2a 0a 2a 2a 20 7b 46 31 36 37 30 36 7d 20 54 68  *.** {F16706} Th
33470 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65  e name of the re
33480 71 75 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e  quested collatin
33490 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65  g function passe
334a0 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  d in the.**     
334b0 20 20 20 20 20 34 74 68 20 70 61 72 61 6d 65 74       4th paramet
334c0 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
334d0 63 6b 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69  ck is in UTF-8 i
334e0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  f the callback.*
334f0 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20 72  *          was r
33500 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
33510 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
33520 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
33530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
33540 69 6e 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  in UTF-16 native
33550 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 74   byte order if t
33560 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a  he callback was.
33570 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
33580 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71  stered using [sq
33590 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
335a0 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a  needed16()]..**.
335b0 2a 2a 20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ** .*/.int sqlit
335c0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
335d0 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
335e0 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
335f0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
33600 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
33610 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
33620 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
33630 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
33640 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
33650 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
33660 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
33670 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
33680 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
33690 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
336a0 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
336b0 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
336c0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
336d0 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
336e0 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
336f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
33700 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
33710 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
33720 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
33730 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
33740 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
33750 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
33760 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
33770 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
33780 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
33790 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
337a0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
337b0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
337c0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
337d0 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
337e0 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
337f0 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
33800 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
33810 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
33820 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
33830 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
33840 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
33850 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
33860 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
33870 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
33880 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
33890 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
338a0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
338b0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
338c0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
338d0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
338e0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
338f0 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
33900 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
33910 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
33920 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
33930 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
33940 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
33950 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
33960 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
33970 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53  .** CAPI3REF:  S
33980 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
33990 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
339a0 65 20 7b 46 31 30 35 33 30 7d 0a 2a 2a 0a 2a 2a  e {F10530}.**.**
339b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65   The sqlite3_sle
339c0 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ep() function.**
339d0 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72   causes the curr
339e0 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75  ent thread to su
339f0 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a  spend execution.
33a00 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20  ** for at least 
33a10 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  a number of mill
33a20 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69  iseconds specifi
33a30 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65  ed in its parame
33a40 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ter..**.** If th
33a50 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
33a60 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70  em does not supp
33a70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73  ort sleep reques
33a80 74 73 20 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c  ts with .** mill
33a90 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
33aa0 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
33ab0 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
33ac0 6f 75 6e 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a  ounded up to .**
33ad0 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63   the nearest sec
33ae0 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20  ond. The number 
33af0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
33b00 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c  of sleep actuall
33b10 79 20 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  y .** requested 
33b20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
33b30 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
33b40 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  urned..**.** SQL
33b50 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
33b60 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79  his interface by
33b70 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c   calling the xSl
33b80 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  eep().** method 
33b90 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
33ba0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
33bb0 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ect..**.** INVAR
33bc0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
33bd0 30 35 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  0533} The [sqlit
33be0 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74  e3_sleep(M)] int
33bf0 65 72 66 61 63 65 20 69 6e 76 6f 6b 65 73 20 74  erface invokes t
33c00 68 65 20 78 53 6c 65 65 70 0a 2a 2a 20 20 20 20  he xSleep.**    
33c10 20 20 20 20 20 20 6d 65 74 68 6f 64 20 6f 66 20        method of 
33c20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
33c30 69 74 65 33 5f 76 66 73 7c 56 46 53 5d 20 69 6e  ite3_vfs|VFS] in
33c40 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 20 20 20   order to.**    
33c50 20 20 20 20 20 20 73 75 73 70 65 6e 64 20 65 78        suspend ex
33c60 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63  ecution of the c
33c70 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 66 6f  urrent thread fo
33c80 72 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 20 20  r at least.**   
33c90 20 20 20 20 20 20 20 4d 20 6d 69 6c 6c 69 73 65         M millise
33ca0 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  conds..**.** {F1
33cb0 30 35 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  0536} The [sqlit
33cc0 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74  e3_sleep(M)] int
33cd0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
33ce0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
33cf0 20 20 20 20 20 20 20 20 20 6d 69 6c 6c 69 73 65           millise
33d00 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
33d10 63 74 75 61 6c 6c 79 20 72 65 71 75 65 73 74 65  ctually requeste
33d20 64 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69  d of the operati
33d30 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  ng.**          s
33d40 79 73 74 65 6d 2c 20 77 68 69 63 68 20 6d 69 67  ystem, which mig
33d50 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
33d60 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
33d70 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  M..*/.int sqlite
33d80 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
33d90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
33da0 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
33db0 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
33dc0 72 61 72 79 20 46 69 6c 65 73 20 7b 46 31 30 33  rary Files {F103
33dd0 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69  10}.**.** If thi
33de0 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
33df0 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
33e00 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  nt to a string w
33e10 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e  hich is.** the n
33e20 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20  ame of a folder 
33e30 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72  (a.k.a. director
33e40 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d  y), then all tem
33e50 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20  porary files.** 
33e60 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74  created by SQLit
33e70 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  e will be placed
33e80 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
33e90 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 72  ry.  If this var
33ea0 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55 4c 4c  iable.** is NULL
33eb0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
33ec0 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73 65 61  QLite does a sea
33ed0 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
33ee0 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61 72 79  priate temporary
33ef0 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63 74 6f  .** file directo
33f00 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
33f10 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69  not safe to modi
33f20 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
33f30 20 6f 6e 63 65 20 61 20 64 61 74 61 62 61 73 65   once a database
33f40 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 68   connection.** h
33f50 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  as been opened. 
33f60 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
33f70 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
33f80 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
33f90 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
33fa0 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
33fb0 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
33fc0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
33fd0 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
33fe0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61  have been call a
33ff0 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  nd remain unchan
34000 67 65 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a  ged thereafter..
34010 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
34020 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
34030 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
34040 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34050 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20   Test To See If 
34060 54 68 65 20 44 61 74 61 62 61 73 65 20 49 73 20  The Database Is 
34070 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  In Auto-Commit M
34080 6f 64 65 20 7b 46 31 32 39 33 30 7d 0a 2a 2a 0a  ode {F12930}.**.
34090 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
340a0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20  et_autocommit() 
340b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
340c0 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a  s non-zero or.**
340d0 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76   zero if the giv
340e0 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  en database conn
340f0 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20  ection is or is 
34100 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69  not in autocommi
34110 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65  t mode,.** respe
34120 63 74 69 76 65 6c 79 2e 20 20 20 41 75 74 6f 63  ctively.   Autoc
34130 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e  ommit mode is on
34140 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2e 20  .** by default. 
34150 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
34160 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
34170 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d  a [BEGIN] statem
34180 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d  ent..** Autocomm
34190 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e  it mode is re-en
341a0 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d  abled by a [COMM
341b0 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
341c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74  ]..**.** If cert
341d0 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72  ain kinds of err
341e0 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73  ors occur on a s
341f0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
34200 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e  a multi-statemen
34210 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  t.** transaction
34220 73 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64  s (errors includ
34230 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c  ing [SQLITE_FULL
34240 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ], [SQLITE_IOERR
34250 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  ], .** [SQLITE_N
34260 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  OMEM], [SQLITE_B
34270 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  USY], and [SQLIT
34280 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68  E_INTERRUPT]) th
34290 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61  en the.** transa
342a0 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72  ction might be r
342b0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
342c0 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f  atically.  The o
342d0 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69  nly way to.** fi
342e0 6e 64 20 6f 75 74 20 69 66 20 53 51 4c 69 74 65  nd out if SQLite
342f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
34300 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
34310 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
34320 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
34330 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
34340 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  tion..**.** INVA
34350 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
34360 31 32 39 33 31 7d 20 54 68 65 20 5b 73 71 6c 69  12931} The [sqli
34370 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
34380 69 74 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65  it(D)] interface
34390 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
343a0 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  o or.**         
343b0 20 7a 65 72 6f 20 69 66 20 74 68 65 20 5b 64 61   zero if the [da
343c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
343d0 6e 5d 20 44 20 69 73 20 6f 72 20 69 73 20 6e 6f  n] D is or is no
343e0 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a  t in autocommit.
343f0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 64 65  **          mode
34400 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
34410 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 32 7d 20 41  **.** {F12932} A
34420 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
34430 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
34440 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 33 7d 20  .**.** {F12933} 
34450 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
34460 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61  is disabled by a
34470 20 73 75 63 63 65 73 73 66 75 6c 20 5b 42 45 47   successful [BEG
34480 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  IN] statement..*
34490 2a 0a 2a 2a 20 7b 46 31 32 39 33 34 7d 20 41 75  *.** {F12934} Au
344a0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
344b0 20 65 6e 61 62 6c 65 64 20 62 79 20 61 20 73 75   enabled by a su
344c0 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54  ccessful [COMMIT
344d0 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a  ] or [ROLLBACK].
344e0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74  **          stat
344f0 65 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a 0a 2a 2a  ement..** .**.**
34500 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
34510 2a 0a 2a 2a 20 7b 55 31 32 39 33 36 7d 20 49 66  *.** {U12936} If
34520 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
34530 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f  changes the auto
34540 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66  commit status of
34550 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
34560 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63            connec
34570 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
34580 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
34590 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
345a0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  urn value.**    
345b0 20 20 20 20 20 20 69 73 20 75 6e 64 65 66 69 6e        is undefin
345c0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
345d0 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
345e0 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
345f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 46  .** CAPI3REF:  F
34600 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65  ind The Database
34610 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65   Handle Of A Pre
34620 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
34630 7b 46 31 33 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13120}.**.** T
34640 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
34650 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  ndle interface.*
34660 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 73  * returns the [s
34670 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73  qlite3*] databas
34680 65 20 68 61 6e 64 6c 65 20 74 6f 20 77 68 69 63  e handle to whic
34690 68 20 61 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  h a.** [prepared
346a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f   statement] belo
346b0 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 64 61 74 61  ngs..** The data
346c0 62 61 73 65 20 68 61 6e 64 6c 65 20 72 65 74 75  base handle retu
346d0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
346e0 64 62 5f 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20  db_handle.** is 
346f0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
34700 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61  e handle that wa
34710 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 61  s.** the first a
34720 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
34730 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
34740 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
34750 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74 20 77 61  iants.** that wa
34760 73 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  s used to create
34770 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
34780 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
34790 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
347a0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31  NTS:.**.** {F131
347b0 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  23} The [sqlite3
347c0 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69  _db_handle(S)] i
347d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
347e0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
347f0 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 5b 64         to the [d
34800 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34810 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  on] associated w
34820 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
34830 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34840 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74  ent] S..*/.sqlit
34850 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68  e3 *sqlite3_db_h
34860 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  andle(sqlite3_st
34870 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
34880 49 33 52 45 46 3a 20 20 46 69 6e 64 20 74 68 65  I3REF:  Find the
34890 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73   next prepared s
348a0 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 31 34 30  tatement {F13140
348b0 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 61  }.**.** Return a
348c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
348d0 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73  next [prepared s
348e0 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 20  tatement] after 
348f0 70 53 74 6d 74 0a 2a 2a 20 61 73 73 6f 63 69 61  pStmt.** associa
34900 74 65 64 20 77 69 74 68 20 5b 64 61 74 61 62 61  ted with [databa
34910 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
34920 44 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69 73  Db.  If pStmt is
34930 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 72 65   NULL.** then re
34940 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  turn a pointer t
34950 6f 20 74 68 65 20 66 69 72 73 74 20 5b 70 72 65  o the first [pre
34960 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
34970 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
34980 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
34990 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44  e connection] pD
349a0 62 2e 20 20 49 66 20 6e 6f 20 5b 70 72 65 70 61  b.  If no [prepa
349b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
349c0 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20  * satisfies the 
349d0 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68  conditions of th
349e0 69 73 20 72 6f 75 74 69 6e 65 2c 20 72 65 74 75  is routine, retu
349f0 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49  rn NULL..**.** I
34a00 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
34a10 20 7b 46 31 33 31 34 33 7d 20 49 66 20 44 20 69   {F13143} If D i
34a20 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
34a30 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 68  nnection] that h
34a40 6f 6c 64 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  olds one or more
34a50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 66  .**          unf
34a60 69 6e 61 6c 69 7a 65 64 20 5b 70 72 65 70 61 72  inalized [prepar
34a70 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61  ed statements] a
34a80 6e 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  nd S is a NULL p
34a90 6f 69 6e 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20  ointer,.**      
34aa0 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
34ab0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53  3_next_stmt(D, S
34ac0 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c  )] routine shall
34ad0 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65   return a pointe
34ae0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  r.**          to
34af0 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 70 72 65   one of the [pre
34b00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
34b10 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  ] associated wit
34b20 68 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31  h D..**.** {F131
34b30 34 36 7d 20 49 66 20 44 20 69 73 20 61 20 5b 64  46} If D is a [d
34b40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34b50 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73 20 6e  on] that holds n
34b60 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e  o.**          un
34b70 66 69 6e 61 6c 69 7a 65 64 20 5b 70 72 65 70 61  finalized [prepa
34b80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
34b90 61 6e 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20  and S is a NULL 
34ba0 70 6f 69 6e 74 65 72 2c 0a 2a 2a 20 20 20 20 20  pointer,.**     
34bb0 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74       then [sqlit
34bc0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20  e3_next_stmt(D, 
34bd0 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c  S)] routine shal
34be0 6c 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 0a  l return a NULL.
34bf0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e  **          poin
34c00 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31  ter..**.** {F131
34c10 34 39 7d 20 49 66 20 53 20 69 73 20 61 20 5b 70  49} If S is a [p
34c20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34c30 74 5d 20 69 6e 20 5b 64 61 74 61 62 61 73 65 20  t] in [database 
34c40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
34c50 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 53 20            and S 
34c60 69 73 20 6e 6f 74 20 74 68 65 20 6c 61 73 74 20  is not the last 
34c70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34c80 65 6e 74 5d 20 69 6e 20 44 2c 20 74 68 65 6e 0a  ent] in D, then.
34c90 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
34ca0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44  ite3_next_stmt(D
34cb0 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  , S)] routine sh
34cc0 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 6f 69  all return a poi
34cd0 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  nter.**         
34ce0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72   to the next [pr
34cf0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34d00 5d 20 69 6e 20 44 20 61 66 74 65 72 20 53 2e 0a  ] in D after S..
34d10 2a 2a 0a 2a 2a 20 7b 46 31 33 31 35 32 7d 20 49  **.** {F13152} I
34d20 66 20 53 20 69 73 20 74 68 65 20 6c 61 73 74 20  f S is the last 
34d30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34d40 65 6e 74 5d 20 69 6e 20 5b 64 61 74 61 62 61 73  ent] in [databas
34d50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
34d60 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
34d70 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
34d80 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69  tmt(D, S)] routi
34d90 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  ne shall return 
34da0 61 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  a NULL.**       
34db0 20 20 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a     pointer..**.*
34dc0 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  /.sqlite3_stmt *
34dd0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
34de0 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20  t(sqlite3 *pDb, 
34df0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
34e00 74 6d 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt);.../*.** CA
34e10 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41  PI3REF: Commit A
34e20 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69  nd Rollback Noti
34e30 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
34e40 6b 73 20 7b 46 31 32 39 35 30 7d 0a 2a 2a 0a 2a  ks {F12950}.**.*
34e50 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
34e60 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  mmit_hook() inte
34e70 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
34e80 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
34e90 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
34ea0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
34eb0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63  transaction is c
34ec0 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79  ommitted..** Any
34ed0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
34ee0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
34ef0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
34f00 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
34f10 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
34f20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
34f30 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
34f40 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  The sqlite3_roll
34f50 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  back_hook() inte
34f60 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
34f70 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
34f80 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
34f90 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
34fa0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63  transaction is c
34fb0 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79  ommitted..** Any
34fc0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
34fd0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
34fe0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
34ff0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
35000 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
35010 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
35020 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
35030 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
35040 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
35050 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ugh.** to the ca
35060 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74 68 65 20  llback.  If the 
35070 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f  callback on a co
35080 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69  mmit hook functi
35090 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e  on .** returns n
350a0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
350b0 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76  e commit is conv
350c0 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
350d0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  lback..**.** If 
350e0 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  another function
350f0 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20   was previously 
35100 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a  registered, its.
35110 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20 69 73  ** pArg value is
35120 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
35130 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65  rwise NULL is re
35140 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  turned..**.** Re
35150 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c  gistering a NULL
35160 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
35170 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  es the callback.
35180 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70  .**.** For the p
35190 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
351a0 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69  API, a transacti
351b0 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  on is said to ha
351c0 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c  ve been .** roll
351d0 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78  ed back if an ex
351e0 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b  plicit "ROLLBACK
351f0 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65  " statement is e
35200 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61  xecuted, or.** a
35210 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74  n error or const
35220 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20  raint causes an 
35230 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63  implicit rollbac
35240 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54  k to occur..** T
35250 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
35260 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
35270 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
35280 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d  tion is.** autom
35290 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
352a0 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65  back because the
352b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
352c0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
352d0 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  ** The rollback 
352e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
352f0 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
35300 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72  nsaction is.** r
35310 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
35320 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c  se a commit call
35330 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f  back returned no
35340 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f  n-zero..** <todo
35350 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20  > Check on this 
35360 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 54 68  </todo>.**.** Th
35370 65 73 65 20 61 72 65 20 65 78 70 65 72 69 6d 65  ese are experime
35380 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  ntal interfaces 
35390 61 6e 64 20 61 72 65 20 73 75 62 6a 65 63 74 20  and are subject 
353a0 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a  to change..**.**
353b0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
353c0 2a 2a 20 7b 46 31 32 39 35 31 7d 20 54 68 65 20  ** {F12951} The 
353d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
353e0 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
353f0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
35400 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
35410 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
35420 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on F to be invok
35430 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
35440 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20   P whenever.**  
35450 20 20 20 20 20 20 20 20 61 20 74 72 61 6e 73 61          a transa
35460 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20 6f 6e  ction commits on
35470 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35480 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
35490 7b 46 31 32 39 35 32 7d 20 54 68 65 20 5b 73 71  {F12952} The [sq
354a0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
354b0 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66  k(D,F,P)] interf
354c0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
354d0 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  P.**          ar
354e0 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
354f0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69  previous call wi
35500 74 68 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20  th the same .** 
35510 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
35520 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20  se connection ] 
35530 44 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74  D , or NULL on t
35540 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a  he first call.**
35550 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20            for a 
35560 70 61 72 74 69 63 75 6c 61 72 20 5b 64 61 74 61  particular [data
35570 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35580 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35   D..**.** {F1295
35590 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  3} Each call to 
355a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
355b0 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74  hook()] overwrit
355c0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
355d0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
355e0 73 74 65 72 65 64 20 62 79 20 70 72 69 6f 72 20  stered by prior 
355f0 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  calls..**.** {F1
35600 32 39 35 34 7d 20 49 66 20 74 68 65 20 46 20 61  2954} If the F a
35610 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
35620 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
35630 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a  D,F,P)] is NULL.
35640 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
35650 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
35660 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e   callback is can
35670 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c  celed and no cal
35680 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
35690 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65    is invoked whe
356a0 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  n a transaction 
356b0 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b  commits..**.** {
356c0 46 31 32 39 35 35 7d 20 49 66 20 74 68 65 20 63  F12955} If the c
356d0 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72  ommit callback r
356e0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20  eturns non-zero 
356f0 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  then the commit 
35700 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  is.**          c
35710 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
35720 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
35730 7b 46 31 32 39 36 31 7d 20 54 68 65 20 5b 73 71  {F12961} The [sq
35740 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
35750 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
35760 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
35770 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
35780 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
35790 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n F to be invoke
357a0 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
357b0 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20  P whenever.**   
357c0 20 20 20 20 20 20 20 61 20 74 72 61 6e 73 61 63         a transac
357d0 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 20  tion rolls back 
357e0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
357f0 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
35800 2a 20 7b 46 31 32 39 36 32 7d 20 54 68 65 20 5b  * {F12962} The [
35810 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
35820 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e  _hook(D,F,P)] in
35830 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35840 74 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20  the P.**        
35850 20 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20    argument from 
35860 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
35870 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  l with the same 
35880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
35890 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
358a0 6e 20 5d 20 44 20 2c 20 6f 72 20 4e 55 4c 4c 20  n ] D , or NULL 
358b0 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  on the first cal
358c0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f  l.**          fo
358d0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b  r a particular [
358e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
358f0 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
35900 31 32 39 36 33 7d 20 45 61 63 68 20 63 61 6c 6c  12963} Each call
35910 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c   to [sqlite3_rol
35920 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76  lback_hook()] ov
35930 65 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c  erwrites the cal
35940 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
35950 20 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20    registered by 
35960 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a  prior calls..**.
35970 2a 2a 20 7b 46 31 32 39 36 34 7d 20 49 66 20 74  ** {F12964} If t
35980 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f  he F argument to
35990 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
359a0 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  ck_hook(D,F,P)] 
359b0 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20  is NULL.**      
359c0 20 20 20 20 74 68 65 6e 20 74 68 65 20 72 6f 6c      then the rol
359d0 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62  lback hook callb
359e0 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 65 64 20  ack is canceled 
359f0 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a  and no callback.
35a00 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69  **          is i
35a10 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72  nvoked when a tr
35a20 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20  ansaction rolls 
35a30 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  back..*/.void *s
35a40 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
35a50 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ok(sqlite3*, int
35a60 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
35a70 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
35a80 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
35a90 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
35aa0 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a  )(void *), void*
35ab0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35ac0 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20  EF: Data Change 
35ad0 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
35ae0 6c 62 61 63 6b 73 20 7b 46 31 32 39 37 30 7d 0a  lbacks {F12970}.
35af0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
35b00 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20  3_update_hook() 
35b10 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 67  interface.** reg
35b20 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
35b30 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  k function with 
35b40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
35b50 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69 66 69  nection identifi
35b60 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
35b70 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
35b80 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
35b90 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
35ba0 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
35bb0 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e  r deleted..** An
35bc0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
35bd0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
35be0 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  l to this functi
35bf0 6f 6e 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  on for the same 
35c00 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
35c10 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
35c20 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  idden..**.** The
35c30 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
35c40 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
35c50 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f   the function to
35c60 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 20 0a   invoke when a .
35c70 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65  ** row is update
35c80 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
35c90 65 6c 65 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20  eleted. .** The 
35ca0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
35cb0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
35cc0 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74  s.** a copy of t
35cd0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
35ce0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64  t to sqlite3_upd
35cf0 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54  ate_hook()..** T
35d00 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61  he second callba
35d10 63 6b 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ck .** argument 
35d20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
35d30 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49  E_INSERT], [SQLI
35d40 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53  TE_DELETE] or [S
35d50 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a  QLITE_UPDATE],.*
35d60 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  * depending on t
35d70 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  he operation tha
35d80 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c  t caused the cal
35d90 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f  lback to be invo
35da0 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72  ked..** The thir
35db0 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 74 68  d and .** fourth
35dc0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
35dd0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
35de0 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  in pointers to t
35df0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
35e00 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65 20 63  .** table name c
35e10 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66  ontaining the af
35e20 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54  fected row..** T
35e30 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63  he final callbac
35e40 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 0a  k parameter is .
35e50 2a 2a 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  ** the rowid of 
35e60 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74  the row..** In t
35e70 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70  he case of an up
35e80 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68  date, this is th
35e90 65 20 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a  e rowid after .*
35ea0 2a 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b  * the update tak
35eb0 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  es place..**.** 
35ec0 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
35ed0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
35ee0 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
35ef0 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
35f00 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
35f10 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
35f20 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
35f30 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ce)..**.** If an
35f40 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
35f50 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
35f60 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41  gistered, its pA
35f70 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72  rg value.** is r
35f80 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
35f90 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  ise NULL is retu
35fa0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  rned..**.** INVA
35fb0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
35fc0 31 32 39 37 31 7d 20 54 68 65 20 5b 73 71 6c 69  12971} The [sqli
35fd0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
35fe0 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
35ff0 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63  e causes callbac
36000 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  k.**          fu
36010 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69  nction F to be i
36020 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 69 72 73  nvoked with firs
36030 74 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68  t parameter P wh
36040 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20  enever.**       
36050 20 20 20 61 20 74 61 62 6c 65 20 72 6f 77 20 69     a table row i
36060 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65  s modified, inse
36070 72 74 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64  rted, or deleted
36080 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   on.**          
36090 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
360a0 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
360b0 46 31 32 39 37 33 7d 20 54 68 65 20 5b 73 71 6c  F12973} The [sql
360c0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
360d0 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
360e0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  ce returns the v
360f0 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
36100 20 6f 66 20 50 20 66 6f 72 20 74 68 65 20 70 72   of P for the pr
36110 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74  evious call on t
36120 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
36130 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
36140 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
36150 4e 55 4c 4c 20 66 6f 72 20 74 68 65 20 66 69 72  NULL for the fir
36160 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  st call..**.** {
36170 46 31 32 39 37 35 7d 20 49 66 20 74 68 65 20 75  F12975} If the u
36180 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62  pdate hook callb
36190 61 63 6b 20 46 20 69 6e 20 5b 73 71 6c 69 74 65  ack F in [sqlite
361a0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
361b0 46 2c 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  F,P)].**        
361c0 20 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74    is NULL then t
361d0 68 65 20 6e 6f 20 75 70 64 61 74 65 20 63 61 6c  he no update cal
361e0 6c 62 61 63 6b 73 20 61 72 65 20 6d 61 64 65 2e  lbacks are made.
361f0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 37 7d 20  .**.** {F12977} 
36200 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
36210 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
36220 6b 28 44 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69  k(D,F,P)] overri
36230 64 65 73 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a  des prior calls.
36240 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
36250 68 65 20 73 61 6d 65 20 69 6e 74 65 72 66 61 63  he same interfac
36260 65 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  e on the same [d
36270 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36280 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
36290 32 39 37 39 7d 20 54 68 65 20 75 70 64 61 74 65  2979} The update
362a0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69   hook callback i
362b0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
362c0 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74  en internal syst
362d0 65 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  em.**          t
362e0 61 62 6c 65 73 20 73 75 63 68 20 61 73 20 73 71  ables such as sq
362f0 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
36300 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 20  sqlite_sequence 
36310 61 72 65 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  are modified..**
36320 0a 2a 2a 20 7b 46 31 32 39 38 31 7d 20 54 68 65  .** {F12981} The
36330 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
36340 72 20 74 6f 20 74 68 65 20 75 70 64 61 74 65 20  r to the update 
36350 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 20 20 20  callback .**    
36360 20 20 20 20 20 20 69 73 20 6f 6e 65 20 6f 66 20        is one of 
36370 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
36380 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
36390 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41   or [SQLITE_UPDA
363a0 54 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  TE],.**         
363b0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
363c0 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  e operation that
363d0 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c   caused the call
363e0 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b  back to be invok
363f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38  ed..**.** {F1298
36400 33 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  3} The third and
36410 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
36420 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
36430 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
36440 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  rs.**          t
36450 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
36460 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20  d UTF-8 strings 
36470 77 68 69 63 68 20 61 72 65 20 74 68 65 20 6e 61  which are the na
36480 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  mes of the.**   
36490 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20         database 
364a0 61 6e 64 20 74 61 62 6c 65 20 74 68 61 74 20 69  and table that i
364b0 73 20 62 65 69 6e 67 20 75 70 64 61 74 65 64 2e  s being updated.
364c0 0a 0a 2a 2a 20 7b 46 31 32 39 38 35 7d 20 54 68  ..** {F12985} Th
364d0 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b  e final callback
364e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
364f0 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72  e rowid of the r
36500 6f 77 20 61 66 74 65 72 0a 2a 2a 20 20 20 20 20  ow after.**     
36510 20 20 20 20 20 74 68 65 20 63 68 61 6e 67 65 20       the change 
36520 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20  occurs..*/.void 
36530 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  *sqlite3_update_
36540 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a  hook(.  sqlite3*
36550 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
36560 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f  d *,int ,char co
36570 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74  nst *,char const
36580 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34   *,sqlite3_int64
36590 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f  ),.  void*.);../
365a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
365b0 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
365c0 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20 43  e Shared Pager C
365d0 61 63 68 65 20 7b 46 31 30 33 33 30 7d 0a 2a 2a  ache {F10330}.**
365e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72   KEYWORDS: {shar
365f0 65 64 20 63 61 63 68 65 7d 20 7b 73 68 61 72 65  ed cache} {share
36600 64 20 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a  d cache mode}.**
36610 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
36620 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
36630 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67  bles the sharing
36640 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
36650 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63   cache.** and sc
36660 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74  hema data struct
36670 75 72 65 73 20 62 65 74 77 65 65 6e 20 63 6f 6e  ures between con
36680 6e 65 63 74 69 6f 6e 73 20 74 6f 20 74 68 65 20  nections to the 
36690 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 0a 2a  same database..*
366a0 2a 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61  * Sharing is ena
366b0 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
366c0 6d 65 6e 74 20 69 73 20 74 72 75 65 20 61 6e 64  ment is true and
366d0 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65   disabled if the
366e0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20   argument.** is 
366f0 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63  false..**.** Cac
36700 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e  he sharing is en
36710 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c  abled and disabl
36720 65 64 0a 2a 2a 20 66 6f 72 20 61 6e 20 65 6e 74  ed.** for an ent
36730 69 72 65 20 70 72 6f 63 65 73 73 2e 20 7b 45 4e  ire process. {EN
36740 44 7d 20 54 68 69 73 20 69 73 20 61 20 63 68 61  D} This is a cha
36750 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65  nge as of SQLite
36760 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 0a   version 3.5.0..
36770 2a 2a 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73  ** In prior vers
36780 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 20  ions of SQLite, 
36790 73 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65  sharing was.** e
367a0 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
367b0 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65  ed for each thre
367c0 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  ad separately..*
367d0 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73  *.** The cache s
367e0 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20  haring mode set 
367f0 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  by this interfac
36800 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75  e effects all su
36810 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
36820 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  s to [sqlite3_op
36830 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
36840 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
36850 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
36860 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  )]..** Existing 
36870 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36880 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73  ions continue us
36890 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  e the sharing mo
368a0 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69  de.** that was i
368b0 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20  n effect at the 
368c0 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f  time they were o
368d0 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72  pened..**.** Vir
368e0 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e  tual tables cann
368f0 6f 74 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ot be used with 
36900 61 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20  a shared cache. 
36910 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a    When shared.**
36920 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
36930 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d, the [sqlite3_
36940 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
36950 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67   API used to reg
36960 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c  ister.** virtual
36970 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77   tables will alw
36980 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72  ays return an er
36990 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ror..**.** This 
369a0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
369b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73  [SQLITE_OK] if s
369c0 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 0a  hared cache was.
369d0 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  ** enabled or di
369e0 73 61 62 6c 65 64 20 73 75 63 63 65 73 73 66 75  sabled successfu
369f0 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20  lly.  An [error 
36a00 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75  code].** is retu
36a10 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a  rned otherwise..
36a20 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63  **.** Shared cac
36a30 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  he is disabled b
36a40 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74  y default. But t
36a50 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65  his might change
36a60 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65   in.** future re
36a70 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
36a80 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
36a90 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20  that care about 
36aa0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
36ab0 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73  setting should s
36ac0 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79  et it explicitly
36ad0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
36ae0 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 30 33  TS:.** .** {F103
36af0 33 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  31} A successful
36b00 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
36b10 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
36b20 68 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 0a  hared_cache(B)].
36b30 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  **          will
36b40 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
36b50 6c 65 20 73 68 61 72 65 64 20 63 61 63 68 65 20  le shared cache 
36b60 6d 6f 64 65 20 66 6f 72 20 61 6e 79 20 73 75 62  mode for any sub
36b70 73 65 71 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20  sequently.**    
36b80 20 20 20 20 20 20 63 72 65 61 74 65 64 20 5b 64        created [d
36b90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36ba0 6f 6e 5d 20 69 6e 20 74 68 65 20 73 61 6d 65 20  on] in the same 
36bb0 70 72 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b  process..**.** {
36bc0 46 31 30 33 33 36 7d 20 57 68 65 6e 20 73 68 61  F10336} When sha
36bd0 72 65 64 20 63 61 63 68 65 20 69 73 20 65 6e 61  red cache is ena
36be0 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74  bled, the [sqlit
36bf0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
36c00 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
36c10 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 61  interface will a
36c20 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20  lways return an 
36c30 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  error..**.** {F1
36c40 30 33 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  0337} The [sqlit
36c50 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
36c60 5f 63 61 63 68 65 28 42 29 5d 20 69 6e 74 65 72  _cache(B)] inter
36c70 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
36c80 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
36c90 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
36ca0 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
36cb0 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63   or disabled suc
36cc0 63 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  cessfully..**.**
36cd0 20 7b 46 31 30 33 33 39 7d 20 53 68 61 72 65 64   {F10339} Shared
36ce0 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
36cf0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
36d00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
36d10 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
36d20 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e(int);../*.** C
36d30 41 50 49 33 52 45 46 3a 20 20 41 74 74 65 6d 70  API3REF:  Attemp
36d40 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d  t To Free Heap M
36d50 65 6d 6f 72 79 20 7b 46 31 37 33 34 30 7d 0a 2a  emory {F17340}.*
36d60 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
36d70 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
36d80 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
36d90 6d 70 74 73 20 74 6f 0a 2a 2a 20 66 72 65 65 20  mpts to.** free 
36da0 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 20  N bytes of heap 
36db0 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f  memory by deallo
36dc0 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e  cating non-essen
36dd0 74 69 61 6c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tial memory.** a
36de0 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20  llocations held 
36df0 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
36e00 6c 69 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20  library. {END}  
36e10 4d 65 6d 6f 72 79 20 75 73 65 64 0a 2a 2a 20 74  Memory used.** t
36e20 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65  o cache database
36e30 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76   pages to improv
36e40 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73  e performance is
36e50 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 0a 2a   an example of.*
36e60 2a 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  * non-essential 
36e70 6d 65 6d 6f 72 79 2e 20 20 53 71 6c 69 74 65 33  memory.  Sqlite3
36e80 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
36e90 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  ) returns.** the
36ea0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
36eb0 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c   actually freed,
36ec0 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20   which might be 
36ed0 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20  more or less.** 
36ee0 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  than the amount 
36ef0 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a  requested..**.**
36f00 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
36f10 2a 2a 20 7b 46 31 37 33 34 31 7d 20 54 68 65 20  ** {F17341} The 
36f20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
36f30 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 69 6e 74 65  _memory(N)] inte
36f40 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
36f50 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  o.**          fr
36f60 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65  ee N bytes of he
36f70 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61  ap memory by dea
36f80 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73  llocating non-es
36f90 73 65 6e 74 69 61 6c 0a 2a 2a 20 20 20 20 20 20  sential.**      
36fa0 20 20 20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63      memory alloc
36fb0 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74  ations held by t
36fc0 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72  he database libr
36fd0 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33  ary..**.** {F163
36fe0 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  42} The [sqlite3
36ff0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
37000 4e 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20  N)] returns the 
37010 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20  number.**       
37020 20 20 20 6f 66 20 62 79 74 65 73 20 61 63 74 75     of bytes actu
37030 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 69 63  ally freed, whic
37040 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20  h might be more 
37050 6f 72 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20  or less.**      
37060 20 20 20 20 74 68 61 6e 20 74 68 65 20 61 6d 6f      than the amo
37070 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
37080 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
37090 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74  lease_memory(int
370a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
370b0 45 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c 69  EF:  Impose A Li
370c0 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65  mit On Heap Size
370d0 20 7b 46 31 37 33 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F17350}.**.** 
370e0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  The sqlite3_soft
370f0 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e  _heap_limit() in
37100 74 65 72 66 61 63 65 0a 2a 2a 20 70 6c 61 63 65  terface.** place
37110 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74  s a "soft" limit
37120 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f   on the amount o
37130 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68  f heap memory th
37140 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61  at may be alloca
37150 74 65 64 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65  ted.** by SQLite
37160 2e 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c  . If an internal
37170 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72   allocation is r
37180 65 71 75 65 73 74 65 64 20 0a 2a 2a 20 74 68 61  equested .** tha
37190 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74  t would exceed t
371a0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
371b0 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  it, [sqlite3_rel
371c0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69  ease_memory()] i
371d0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65  s.** invoked one
371e0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
371f0 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73  o free up some s
37200 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 20  pace before the 
37210 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
37220 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   made..**.** The
37230 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64   limit is called
37240 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65   "soft", because
37250 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   if.** [sqlite3_
37260 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
37270 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65  ] cannot.** free
37280 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
37290 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  ry to prevent th
372a0 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69  e limit from bei
372b0 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20  ng exceeded,.** 
372c0 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c  the memory is al
372d0 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 61  located anyway a
372e0 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f  nd the current o
372f0 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
37300 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74  s..**.** A negat
37310 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75  ive or zero valu
37320 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68  e for N means th
37330 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73  at there is no s
37340 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61  oft heap limit a
37350 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  nd.** [sqlite3_r
37360 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
37370 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61   will only be ca
37380 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79  lled when memory
37390 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a   is exhausted..*
373a0 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  * The default va
373b0 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74  lue for the soft
373c0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a   heap limit is z
373d0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ero..**.** SQLit
373e0 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65  e makes a best e
373f0 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74  ffort to honor t
37400 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
37410 69 74 2e 20 20 0a 2a 2a 20 42 75 74 20 69 66 20  it.  .** But if 
37420 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
37430 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f  mit cannot be ho
37440 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 69 6f 6e  nored, execution
37450 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75   will.** continu
37460 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20  e without error 
37470 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e  or notification.
37480 20 20 54 68 69 73 20 69 73 20 77 68 79 20 74 68    This is why th
37490 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a 20 63  e limit is .** c
374a0 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c  alled a "soft" l
374b0 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 76  imit.  It is adv
374c0 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  isory only..**.*
374d0 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74  * Prior to SQLit
374e0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c  e version 3.5.0,
374f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e   this routine on
37500 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74  ly constrained t
37510 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
37520 6f 63 61 74 65 64 20 62 79 20 61 20 73 69 6e 67  ocated by a sing
37530 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68 65 20  le thread - the 
37540 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
37550 68 69 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e  hich this routin
37560 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69  e.** runs.  Begi
37570 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74  nning with SQLit
37580 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c  e version 3.5.0,
37590 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
375a0 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69  imit is.** appli
375b0 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64  ed to all thread
375c0 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73 70 65  s. The value spe
375d0 63 69 66 69 65 64 20 66 6f 72 20 74 68 65 20 73  cified for the s
375e0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a  oft heap limit.*
375f0 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20 62 6f  * is an upper bo
37600 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c  und on the total
37610 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
37620 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61  on for all threa
37630 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f  ds. In.** versio
37640 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73  n 3.5.0 there is
37650 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f   no mechanism fo
37660 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68  r limiting the h
37670 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a  eap usage for.**
37680 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65   individual thre
37690 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ads..**.** INVAR
376a0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
376b0 36 33 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  6351} The [sqlit
376c0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
376d0 69 74 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  it(N)] interface
376e0 20 70 6c 61 63 65 73 20 61 20 73 6f 66 74 20 6c   places a soft l
376f0 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  imit.**         
37700 20 6f 66 20 4e 20 62 79 74 65 73 20 6f 6e 20 74   of N bytes on t
37710 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61  he amount of hea
37720 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61  p memory that ma
37730 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a  y be allocated.*
37740 2a 20 20 20 20 20 20 20 20 20 20 75 73 69 6e 67  *          using
37750 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
37760 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
37770 72 65 61 6c 6c 6f 63 28 29 5d 20 61 74 20 61 6e  realloc()] at an
37780 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 20 20  y point.**      
37790 20 20 20 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a      in time..**.
377a0 2a 2a 20 7b 46 31 36 33 35 32 7d 20 49 66 20 61  ** {F16352} If a
377b0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
377c0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
377d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
377e0 29 5d 20 77 6f 75 6c 64 0a 2a 2a 20 20 20 20 20  )] would.**     
377f0 20 20 20 20 20 63 61 75 73 65 20 74 68 65 20 74       cause the t
37800 6f 74 61 6c 20 61 6d 6f 75 6e 74 20 6f 66 20 61  otal amount of a
37810 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79 20  llocated memory 
37820 74 6f 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a  to exceed the.**
37830 20 20 20 20 20 20 20 20 20 20 73 6f 66 74 20 68            soft h
37840 65 61 70 20 6c 69 6d 69 74 2c 20 74 68 65 6e 20  eap limit, then 
37850 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
37860 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e  _memory()] is in
37870 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  voked.**        
37880 20 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20    in an attempt 
37890 74 6f 20 72 65 64 75 63 65 20 74 68 65 20 6d 65  to reduce the me
378a0 6d 6f 72 79 20 75 73 61 67 65 20 70 72 69 6f 72  mory usage prior
378b0 20 74 6f 20 70 72 6f 63 65 65 64 69 6e 67 0a 2a   to proceeding.*
378c0 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
378d0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
378e0 61 74 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a  ation attempt..*
378f0 2a 0a 2a 2a 20 7b 46 31 36 33 35 33 7d 20 43 61  *.** {F16353} Ca
37900 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
37910 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
37920 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
37930 20 74 68 61 74 20 74 72 69 67 67 65 72 0a 2a 2a   that trigger.**
37940 20 20 20 20 20 20 20 20 20 20 61 74 74 65 6d 70            attemp
37950 74 73 20 74 6f 20 72 65 64 75 63 65 20 6d 65 6d  ts to reduce mem
37960 6f 72 79 20 75 73 61 67 65 20 74 68 72 6f 75 67  ory usage throug
37970 68 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  h the soft heap 
37980 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20  limit.**        
37990 20 20 6d 65 63 68 61 6e 69 73 6d 20 63 6f 6e 74    mechanism cont
379a0 69 6e 75 65 20 65 76 65 6e 20 69 66 20 74 68 65  inue even if the
379b0 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 64 75   attempt to redu
379c0 63 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  ce memory.**    
379d0 20 20 20 20 20 20 75 73 61 67 65 20 69 73 20 75        usage is u
379e0 6e 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2a 0a  nsuccessful..**.
379f0 2a 2a 20 7b 46 31 36 33 35 34 7d 20 41 20 6e 65  ** {F16354} A ne
37a00 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76  gative or zero v
37a10 61 6c 75 65 20 66 6f 72 20 4e 20 69 6e 20 61 20  alue for N in a 
37a20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20  call to.**      
37a30 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66      [sqlite3_sof
37a40 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d  t_heap_limit(N)]
37a50 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72   means that ther
37a60 65 20 69 73 20 6e 6f 20 73 6f 66 74 0a 2a 2a 20  e is no soft.** 
37a70 20 20 20 20 20 20 20 20 20 68 65 61 70 20 6c 69           heap li
37a80 6d 69 74 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  mit and [sqlite3
37a90 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
37aa0 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 0a  )] will only be.
37ab0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
37ac0 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69  ed when memory i
37ad0 73 20 63 6f 6d 70 6c 65 74 65 6c 79 20 65 78 68  s completely exh
37ae0 61 75 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  austed..**.** {F
37af0 31 36 33 35 35 7d 20 54 68 65 20 64 65 66 61 75  16355} The defau
37b00 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  lt value for the
37b10 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
37b20 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20   is zero..**.** 
37b30 7b 46 31 36 33 35 38 7d 20 45 61 63 68 20 63 61  {F16358} Each ca
37b40 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
37b50 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e  oft_heap_limit(N
37b60 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  )] overrides the
37b70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
37b80 75 65 73 20 73 65 74 20 62 79 20 61 6c 6c 20 70  ues set by all p
37b90 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2f 0a 76  rior calls..*/.v
37ba0 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  oid sqlite3_soft
37bb0 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29  _heap_limit(int)
37bc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37bd0 46 3a 20 20 45 78 74 72 61 63 74 20 4d 65 74 61  F:  Extract Meta
37be0 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c  data About A Col
37bf0 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b  umn Of A Table {
37c00 46 31 32 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12850}.**.** Th
37c10 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65  is routine.** re
37c20 74 75 72 6e 73 20 6d 65 74 61 2d 64 61 74 61 20  turns meta-data 
37c30 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63  about a specific
37c40 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65   column of a spe
37c50 63 69 66 69 63 20 64 61 74 61 62 61 73 65 0a 2a  cific database.*
37c60 2a 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62  * table accessib
37c70 6c 65 20 75 73 69 6e 67 20 74 68 65 20 63 6f 6e  le using the con
37c80 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 70  nection handle p
37c90 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
37ca0 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20  st function .** 
37cb0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
37cc0 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64  The column is id
37cd0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
37ce0 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e  second, third an
37cf0 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
37d00 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69 73 20  ers to .** this 
37d10 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65  function. The se
37d20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
37d30 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d  s either the nam
37d40 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
37d50 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e  e.** (i.e. "main
37d60 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20  ", "temp" or an 
37d70 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
37d80 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  e) containing th
37d90 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74  e specified.** t
37da0 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66  able or NULL. If
37db0 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65   it is NULL, the
37dc0 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64  n all attached d
37dd0 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61  atabases are sea
37de0 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65  rched.** for the
37df0 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65   table using the
37e00 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
37e10 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
37e20 65 6e 67 69 6e 65 20 75 73 65 73 20 74 6f 20 0a  engine uses to .
37e30 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61  ** resolve unqua
37e40 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66  lified table ref
37e50 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  erences..**.** T
37e60 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
37e70 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
37e80 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
37e90 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e  are the table an
37ea0 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d  d column .** nam
37eb0 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64  e of the desired
37ec0 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74   column, respect
37ed0 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f  ively. Neither o
37ee0 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
37ef0 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  rs .** may be NU
37f00 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69  LL..**.** Meta i
37f10 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
37f20 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e  turned by writin
37f30 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20  g to the memory 
37f40 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64  locations passed
37f50 20 61 73 0a 2a 2a 20 74 68 65 20 35 74 68 20 61   as.** the 5th a
37f60 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61  nd subsequent pa
37f70 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
37f80 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f   function. Any o
37f90 66 20 74 68 65 73 65 20 0a 2a 2a 20 61 72 67 75  f these .** argu
37fa0 6d 65 6e 74 73 20 6d 61 79 20 62 65 20 4e 55 4c  ments may be NUL
37fb0 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  L, in which case
37fc0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
37fd0 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65  ng element of me
37fe0 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ta .** informati
37ff0 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  on is omitted..*
38000 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50 61  *.** <pre>.** Pa
38010 72 61 6d 65 74 65 72 20 20 20 20 20 4f 75 74 70  rameter     Outp
38020 75 74 20 54 79 70 65 20 20 20 20 20 20 44 65 73  ut Type      Des
38030 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d  cription.** ----
38040 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
38050 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
38060 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20 20 20 20  **.**   5th     
38070 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20      const char* 
38080 20 20 20 20 20 44 61 74 61 20 74 79 70 65 0a 2a       Data type.*
38090 2a 20 20 20 36 74 68 20 20 20 20 20 20 20 20 20  *   6th         
380a0 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20  const char*     
380b0 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 66   Name of the def
380c0 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ault collation s
380d0 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20 20 37 74  equence .**   7t
380e0 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20  h         int   
380f0 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20             True 
38100 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 68 61  if the column ha
38110 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e  s a NOT NULL con
38120 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20 38 74 68  straint.**   8th
38130 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20           int    
38140 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69            True i
38150 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
38160 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d  part of the PRIM
38170 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20 39 74 68  ARY KEY.**   9th
38180 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20           int    
38190 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69            True i
381a0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
381b0 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a  AUTOINCREMENT.**
381c0 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a   </pre>.**.**.**
381d0 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e   The memory poin
381e0 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68  ted to by the ch
381f0 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73  aracter pointers
38200 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68   returned for th
38210 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f  e .** declaratio
38220 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61  n type and colla
38230 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
38240 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69   valid only unti
38250 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a 2a 20 63  l the next .** c
38260 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71 6c 69 74  all to any sqlit
38270 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a  e API function..
38280 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65  **.** If the spe
38290 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20  cified table is 
382a0 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c  actually a view,
382b0 20 74 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 69   then an error i
382c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
382d0 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69  * If the specifi
382e0 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f  ed column is "ro
382f0 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22  wid", "oid" or "
38300 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 20  _rowid_" and an 
38310 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50 52 49 4d  .** INTEGER PRIM
38320 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68  ARY KEY column h
38330 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74  as been explicit
38340 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65  ly declared, the
38350 6e 20 74 68 65 20 6f 75 74 70 75 74 20 0a 2a 2a  n the output .**
38360 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
38370 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c  set for the expl
38380 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
38390 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65  column. If there
383a0 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63   is no.** explic
383b0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 49 50  itly declared IP
383c0 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74  K column, then t
383d0 68 65 20 6f 75 74 70 75 74 20 70 61 72 61 6d 65  he output parame
383e0 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73 20  ters are set as 
383f0 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a  .** follows:.**.
38400 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
38410 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45  data type: "INTE
38420 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c  GER".**     coll
38430 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20  ation sequence: 
38440 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20  "BINARY".**     
38450 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20  not null: 0.**  
38460 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20     primary key: 
38470 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e  1.**     auto in
38480 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f  crement: 0.** </
38490 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  pre>.**.** This 
384a0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61  function may loa
384b0 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63  d one or more sc
384c0 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62  hemas from datab
384d0 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e  ase files. If an
384e0 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73  .** error occurs
384f0 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f   during this pro
38500 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20  cess, or if the 
38510 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20  requested table 
38520 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e  or column.** can
38530 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e  not be found, an
38540 20 53 51 4c 49 54 45 20 65 72 72 6f 72 20 63 6f   SQLITE error co
38550 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  de is returned a
38560 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  nd an error mess
38570 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69 6e 20 74  age.** left in t
38580 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  he database hand
38590 6c 65 20 28 74 6f 20 62 65 20 72 65 74 72 69 65  le (to be retrie
385a0 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ved using sqlite
385b0 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a  3_errmsg())..**.
385c0 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f  ** This API is o
385d0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
385e0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
385f0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
38600 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41  he.** SQLITE_ENA
38610 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
38620 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ATA preprocessor
38630 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
38640 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
38650 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74  table_column_met
38660 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33  adata(.  sqlite3
38670 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
38680 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69       /* Connecti
38690 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  on handle */.  c
386a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
386b0 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61  me,        /* Da
386c0 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e  tabase name or N
386d0 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ULL */.  const c
386e0 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c  har *zTableName,
386f0 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61       /* Table na
38700 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  me */.  const ch
38710 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c  ar *zColumnName,
38720 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61      /* Column na
38730 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  me */.  char con
38740 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c  st **pzDataType,
38750 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44      /* OUTPUT: D
38760 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70  eclared data typ
38770 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
38780 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20  t **pzCollSeq,  
38790 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f     /* OUTPUT: Co
387a0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
387b0 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   name */.  int *
387c0 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20  pNotNull,       
387d0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
387e0 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55  : True if NOT NU
387f0 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78  LL constraint ex
38800 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  ists */.  int *p
38810 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20  PrimaryKey,     
38820 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
38830 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
38840 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20  part of PK */.  
38850 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20  int *pAutoinc   
38860 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
38870 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
38880 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e  olumn is auto-in
38890 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f  crement */.);../
388a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
388b0 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
388c0 20 7b 46 31 32 36 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F12600}.**.** 
388d0 7b 46 31 32 36 30 31 7d 20 54 68 65 20 73 71 6c  {F12601} The sql
388e0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
388f0 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ion() interface.
38900 2a 2a 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c  ** attempts to l
38910 6f 61 64 20 61 6e 20 53 51 4c 69 74 65 20 65 78  oad an SQLite ex
38920 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20  tension library 
38930 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65  contained in the
38940 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c 65 2e 20   file.** zFile. 
38950 7b 46 31 32 36 30 32 7d 20 54 68 65 20 65 6e 74  {F12602} The ent
38960 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f  ry point is zPro
38970 63 2e 20 7b 46 31 32 36 30 33 7d 20 7a 50 72 6f  c. {F12603} zPro
38980 63 20 6d 61 79 20 62 65 20 30 0a 2a 2a 20 69 6e  c may be 0.** in
38990 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which c