/ Hex Artifact Content
Login

Artifact 06ec1a8643200b9760ffc3e61e99e869b7088f84:


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 35 20 32 30 30 38 2f 30  n,v 1.345 2008/0
05f0: 36 2f 32 31 20 31 33 3a 33 35 3a 35 37 20 6d 69  6/21 13:35:57 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 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
36b0: 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6d  *          and m
36c0: 65 73 73 61 67 65 20 61 63 63 65 73 73 69 62 6c  essage accessibl
36d0: 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65  e via [sqlite3_e
36e0: 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20  rrcode()],.**   
36f0: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
3700: 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b  errmsg()], and [
3710: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
3720: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ()]..**.** {F121
3730: 33 38 7d 20 49 66 20 74 68 65 20 53 20 70 61 72  38} If the S par
3740: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
3750: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c  e3_exec(D,S,C,A,
3760: 45 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  E)] is NULL or a
3770: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6d  n.**          em
3780: 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 63 6f  pty string or co
3790: 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f  ntains nothing o
37a0: 74 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73  ther than whites
37b0: 70 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a  pace, comments,.
37c0: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 2f  **          and/
37d0: 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74  or semicolons, t
37e0: 68 65 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 5b  hen results of [
37f0: 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
3800: 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
3810: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
3820: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
3830: 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20  _errmsg16()].** 
3840: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72           shall r
3850: 65 73 65 74 20 74 6f 20 69 6e 64 69 63 61 74 65  eset to indicate
3860: 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a   no errors..**.*
3870: 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a  * LIMITATIONS:.*
3880: 2a 0a 2a 2a 20 7b 55 31 32 31 34 31 7d 20 54 68  *.** {U12141} Th
3890: 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
38a0: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  r to [sqlite3_ex
38b0: 65 63 28 29 5d 20 6d 75 73 74 20 62 65 20 61 6e  ec()] must be an
38c0: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a   valid and open.
38d0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
38e0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38f0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 32  ]..**.** {U12142
3900: 7d 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63  } The database c
3910: 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
3920: 6f 74 20 62 65 20 63 6c 6f 73 65 64 20 77 68 69  ot be closed whi
3930: 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  le.**          [
3940: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3950: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
3960: 2a 20 7b 55 31 32 31 34 33 7d 20 54 68 65 20 63  * {U12143} The c
3970: 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
3980: 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69  should use [sqli
3990: 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66  te3_free()] to f
39a0: 72 65 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ree.**          
39b0: 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
39c0: 2a 65 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20  *errmsg is left 
39d0: 70 6f 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65  pointing at once
39e0: 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20   the error.**   
39f0: 20 20 20 20 20 20 20 6d 65 73 73 61 67 65 20 69         message i
3a00: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3a10: 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34  ed..**.** {U1214
3a20: 35 7d 20 54 68 65 20 53 51 4c 20 73 74 61 74 65  5} The SQL state
3a30: 6d 65 6e 74 20 74 65 78 74 20 69 6e 20 74 68 65  ment text in the
3a40: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3a50: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
3a60: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  )].**          m
3a70: 75 73 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ust remain uncha
3a80: 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69  nged while [sqli
3a90: 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72  te3_exec()] is r
3aa0: 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
3ab0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
3ac0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
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 2f 2a 20 41 6e 20            /* An 
3af0: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
3b00: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
3b10: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
3b20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3b30: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
3b40: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
3b50: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3b60: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
3b70: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
3b80: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
3b90: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
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 2f 2a 20 31 73 74            /* 1st
3bc0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
3bd0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
3be0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **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 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
3c10: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
3c20: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
3c30: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
3c40: 64 65 73 20 7b 46 31 30 32 31 30 7d 0a 2a 2a 20  des {F10210}.** 
3c50: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
3c60: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d  _OK {error code}
3c70: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a   {error codes}.*
3c80: 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65  *.** Many SQLite
3c90: 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
3ca0: 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73  n an integer res
3cb0: 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68  ult code from th
3cc0: 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68  e set shown.** h
3cd0: 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ere in order to 
3ce0: 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65 73  indicates succes
3cf0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
3d00: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53  .** See also: [S
3d10: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
3d20: 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
3d30: 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65  lt codes].*/.#de
3d40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20  fine SQLITE_OK  
3d50: 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
3d60: 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c  Successful resul
3d70: 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e  t */./* beginnin
3d80: 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  g-of-error-codes
3d90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3da0: 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20  TE_ERROR        
3db0: 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72  1   /* SQL error
3dc0: 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61   or missing data
3dd0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
3de0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20  SQLITE_INTERNAL 
3df0: 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72      2   /* Inter
3e00: 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20  nal logic error 
3e10: 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65  in SQLite */.#de
3e20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d  fine SQLITE_PERM
3e30: 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20           3   /* 
3e40: 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f  Access permissio
3e50: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
3e60: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
3e70: 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43          4   /* C
3e80: 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
3e90: 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f  requested an abo
3ea0: 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  rt */.#define SQ
3eb0: 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20  LITE_BUSY       
3ec0: 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74    5   /* The dat
3ed0: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f  abase file is lo
3ee0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
3ef0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20  SQLITE_LOCKED   
3f00: 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62      6   /* A tab
3f10: 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61  le in the databa
3f20: 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  se is locked */.
3f30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
3f40: 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20  OMEM        7   
3f50: 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61  /* A malloc() fa
3f60: 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  iled */.#define 
3f70: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
3f80: 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d      8   /* Attem
3f90: 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65  pt to write a re
3fa0: 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20  adonly database 
3fb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3fc0: 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39  E_INTERRUPT    9
3fd0: 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
3fe0: 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71  terminated by sq
3ff0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
4000: 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )*/.#define SQLI
4010: 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31  TE_IOERR       1
4020: 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64  0   /* Some kind
4030: 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72   of disk I/O err
4040: 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23  or occurred */.#
4050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
4060: 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f  RRUPT     11   /
4070: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64  * The database d
4080: 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c  isk image is mal
4090: 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e  formed */.#defin
40a0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  e SQLITE_NOTFOUN
40b0: 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54  D    12   /* NOT
40c0: 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20   USED. Table or 
40d0: 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64  record not found
40e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
40f0: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
4100: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
4110: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
4120: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
4130: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4140: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
4150: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4160: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4170: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4180: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4190: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f  OL    15   /* NO
41a0: 54 20 55 53 45 44 2e 20 44 61 74 61 62 61 73 65  T USED. Database
41b0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
41c0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
41d0: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
41e0: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
41f0: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4200: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4210: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4220: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4230: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4240: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4250: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4260: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4270: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
4280: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
4290: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
42a0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
42b0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
42c0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
42d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
42e0: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
42f0: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4300: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4310: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4320: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4330: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4340: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4350: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4360: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4370: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
4380: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
4390: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
43a0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
43b0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
43c0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
43d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43e0: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
43f0: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4400: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4410: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4420: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4430: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4440: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4450: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4460: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4470: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4480: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4490: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
44a0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
44b0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
44c0: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
44d0: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
44e0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
44f0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4500: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4510: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4520: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4530: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4540: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4550: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4560: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4570: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4580: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46   Result Codes {F
4590: 31 30 32 32 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  10220}.** KEYWOR
45a0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72  DS: {extended er
45b0: 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e  ror code} {exten
45c0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d  ded error codes}
45d0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
45e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
45f0: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69  odes}.**.** In i
4600: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ts default confi
4610: 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65  guration, SQLite
4620: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
4630: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69  turn one of 26 i
4640: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
4650: 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
4660: 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20  des].  However, 
4670: 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73  experience has s
4680: 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f  hown that many o
4690: 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c  f.** these resul
46a0: 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20  t codes are too 
46b0: 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20  coarse-grained. 
46c0: 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f   They do not pro
46d0: 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20  vide as.** much 
46e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
46f0: 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72  t problems as pr
4700: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
4710: 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66  like.  In an eff
4720: 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73  ort to.** addres
4730: 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65  s this, newer ve
4740: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
4750: 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20   (version 3.3.8 
4760: 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75  and later) inclu
4770: 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f  de.** support fo
4780: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73  r additional res
4790: 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70  ult codes that p
47a0: 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61  rovide more deta
47b0: 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  iled information
47c0: 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73  .** about errors
47d0: 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72  . The extended r
47e0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
47f0: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
4800: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
4810: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4820: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
4830: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4840: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
4850: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a  codes()] API..**
4860: 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20  .** Some of the 
4870: 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64  available extend
4880: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4890: 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e  are listed here.
48a0: 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65  .** One may expe
48b0: 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ct the number of
48c0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
48d0: 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65   codes will be e
48e0: 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69  xpand.** over ti
48f0: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  me.  Software th
4900: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64  at uses extended
4910: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68   result codes sh
4920: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74  ould expect.** t
4930: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74  o see new result
4940: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65   codes in future
4950: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
4960: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ite..**.** The S
4970: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
4980: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
4990: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
49a0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
49b0: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
49c0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
49d0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 33  S:.**.** {F10223
49e0: 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e  } The symbolic n
49f0: 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e  ame for an exten
4a00: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4a10: 61 6c 77 61 79 73 20 63 6f 6e 74 61 69 6e 73 0a  always contains.
4a20: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65  **          a re
4a30: 6c 61 74 65 64 20 70 72 69 6d 61 72 79 20 72 65  lated primary re
4a40: 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61 20 70  sult code as a p
4a50: 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  refix..**.** {F1
4a60: 30 32 32 34 7d 20 50 72 69 6d 61 72 79 20 72 65  0224} Primary re
4a70: 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20  sult code names 
4a80: 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c 65  contain a single
4a90: 20 22 5f 22 20 63 68 61 72 61 63 74 65 72 2e 0a   "_" character..
4aa0: 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 35 7d 20 45  **.** {F10225} E
4ab0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4ac0: 6f 64 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61 69  ode names contai
4ad0: 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f  n two or more "_
4ae0: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
4af0: 0a 2a 2a 20 7b 46 31 30 32 32 36 7d 20 54 68 65  .** {F10226} The
4b00: 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f   numeric value o
4b10: 66 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65  f an extended re
4b20: 73 75 6c 74 20 63 6f 64 65 20 63 6f 6e 74 61 69  sult code contai
4b30: 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
4b40: 20 20 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65     numeric value
4b50: 20 6f 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f   of its correspo
4b60: 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65  nding primary re
4b70: 73 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20  sult code in.** 
4b80: 20 20 20 20 20 20 20 20 20 69 74 73 20 6c 65 61           its lea
4b90: 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38  st significant 8
4ba0: 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e   bits..*/.#defin
4bb0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4bc0: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
4bd0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4be0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
4bf0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4c00: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20  ORT_READ        
4c10: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c20: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
4c40: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  TE             (
4c50: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c60: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
4c80: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  C             (S
4c90: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
4ca0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
4cc0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51  SYNC         (SQ
4cd0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c  LITE_IOERR | (5<
4ce0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41  ITE_IOERR_TRUNCA
4d00: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TE          (SQL
4d10: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
4d20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d30: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
4d40: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d50: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
4d60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4d70: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
4d80: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4d90: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
4da0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4db0: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
4dc0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4dd0: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29  _IOERR | (9<<8))
4de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4df0: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20  IOERR_DELETE    
4e00: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4e10: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
4e20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4e30: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
4e40: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4e50: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
4e60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4e70: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
4e80: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4e90: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
4ea0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4eb0: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20  IOERR_ACCESS    
4ec0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4ed0: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29  IOERR | (13<<8))
4ee0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ef0: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52  IOERR_CHECKRESER
4f00: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f  VEDLOCK (SQLITE_
4f10: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29  IOERR | (14<<8))
4f20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4f30: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
4f40: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
4f50: 20 7b 46 31 30 32 33 30 7d 0a 2a 2a 0a 2a 2a 20   {F10230}.**.** 
4f60: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
4f70: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
4f80: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
4f90: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
4fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
4fb0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
4fc0: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
4fd0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
4fe0: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
4ff0: 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  od of the.** [sq
5000: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
5010: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
5020: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
5030: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
5040: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
5050: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5060: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5070: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
5080: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5090: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
50a0: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
50b0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
50c0: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
50d0: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
50e0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
50f0: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
5100: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
5110: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
5120: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
5130: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5140: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
5150: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
5160: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
5170: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
5180: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
5190: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
51a0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
51b0: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
51c0: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
51d0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
51e0: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
51f0: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
5200: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
5210: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
5220: 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  02000.#define SQ
5230: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
5240: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
5250: 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  04000../*.** CAP
5260: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
5270: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 46  aracteristics {F
5280: 31 30 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  10240}.**.** The
5290: 20 78 44 65 76 69 63 65 43 61 70 61 62 69 6c 69   xDeviceCapabili
52a0: 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ties method of t
52b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
52c0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
52d0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
52e0: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
52f0: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68  vector of the th
5300: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
5310: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
5320: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
5330: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
5340: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
5350: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
5360: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
5370: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5380: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
5390: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
53a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
53b0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
53c0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
53d0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
53e0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
53f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
5400: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
5410: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
5420: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
5430: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
5440: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
5450: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
5460: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
5470: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
5480: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
5490: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
54a0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
54b0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
54c0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
54d0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
54e0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
54f0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
5500: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
5510: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
5520: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
5530: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
5540: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
5550: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5560: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
5570: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
5580: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
5590: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
55a0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
55b0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
55c0: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23  o xWrite()..*/.#
55d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
55e0: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
55f0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
5600: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5610: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
5620: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23      0x00000002.#
5630: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5640: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20  CAP_ATOMIC1K    
5650: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
5660: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5670: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
5680: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
5690: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
56a0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
56b0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
56c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
56d0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
56e0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
56f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5700: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
5710: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
5720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5730: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
5740: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
5750: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5760: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
5770: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
5780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5790: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
57a0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
57b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
57c0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20  CAP_SEQUENTIAL  
57d0: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a      0x00000400..
57e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
57f0: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
5800: 65 6c 73 20 7b 46 31 30 32 35 30 7d 0a 2a 2a 0a  els {F10250}.**.
5810: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
5820: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
5830: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5840: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
5850: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
5860: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
5870: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
5880: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
5890: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
58a0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
58b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
58c0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
58d0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
58e0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
58f0: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
5900: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5910: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
5920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5930: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
5940: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
5950: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
5960: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
5970: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
5980: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
5990: 6c 61 67 73 20 7b 46 31 30 32 36 30 7d 0a 2a 2a  lags {F10260}.**
59a0: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
59b0: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
59c0: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
59d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
59e0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
59f0: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
5a00: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
5a10: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
5a20: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
5a30: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
5a40: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
5a50: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
5a60: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
5a70: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
5a80: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
5a90: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
5aa0: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
5ab0: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
5ac0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
5ad0: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
5ae0: 65 64 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53  ed. The SQLITE_S
5af0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c 61 67 20  YNC_NORMAL flag 
5b00: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
5b10: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5b20: 65 6d 61 6e 74 69 63 73 2e 20 54 68 65 20 53 51  emantics. The SQ
5b30: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
5b40: 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  lag means.** to 
5b50: 75 73 65 20 4d 61 63 20 4f 53 2d 58 20 73 74 79  use Mac OS-X sty
5b60: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
5b70: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
5b80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b90: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
5ba0: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
5bb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
5bc0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
5bd0: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
5be0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
5bf0: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
5c00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5c10: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
5c20: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 20  pen File Handle 
5c30: 7b 46 31 31 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 41  {F11110}.**.** A
5c40: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
5c50: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
5c60: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
5c70: 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74  in the OS.** int
5c80: 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49  erface layer.  I
5c90: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74  ndividual OS int
5ca0: 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74  erface implement
5cb0: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
5cc0: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
5cd0: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
5ce0: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
5cf0: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
5d00: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
5d10: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
5d20: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
5d30: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
5d40: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
5d50: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
5d60: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
5d70: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
5d80: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
5d90: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
5da0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
5db0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
5dc0: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
5dd0: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
5de0: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
5df0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
5e00: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
5e10: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
5e20: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
5e30: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
5e40: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
5e50: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
5e60: 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 46 31 31  hods Object {F11
5e70: 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  120}.**.** Every
5e80: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
5e90: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
5ea0: 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63  ] xOpen method c
5eb0: 6f 6e 74 61 69 6e 73 20 61 20 70 6f 69 6e 74 65  ontains a pointe
5ec0: 72 20 74 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 61  r to.** an insta
5ed0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
5ee0: 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
5ef0: 20 64 65 66 69 6e 65 73 20 74 68 65 0a 2a 2a 20   defines the.** 
5f00: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
5f10: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
5f20: 6f 70 65 72 61 74 69 6f 6e 73 20 61 67 61 69 6e  operations again
5f30: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
5f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
5f50: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
5f60: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
5f70: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
5f80: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
5f90: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
5fa0: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
5fb0: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
5fc0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
5fd0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
5fe0: 73 20 61 20 4d 61 63 20 4f 53 2d 58 20 73 74 79  s a Mac OS-X sty
5ff0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
6000: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
6010: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
6020: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
6030: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
6040: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
6050: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
6060: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
6070: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
6080: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
6090: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
60a0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
60b0: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
60c0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
60d0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
60e0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
60f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
6100: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
6110: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
6120: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
6130: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
6140: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
6150: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6160: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
6170: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
6180: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
6190: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
61a0: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
61b0: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
61c0: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
61d0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
61e0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
61f0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
6200: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
6210: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
6220: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
6230: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
6240: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
6250: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
6260: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
6270: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
6280: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
6290: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
62a0: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
62b0: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
62c0: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
62d0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
62e0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
62f0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
6300: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
6310: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
6320: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
6330: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
6340: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
6350: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
6360: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
6370: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
6380: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
6390: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
63a0: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
63b0: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
63c0: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
63d0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
63e0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
63f0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
6400: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
6410: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
6420: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
6430: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
6440: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
6450: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
6460: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
6470: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
6480: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
6490: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
64a0: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
64b0: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
64c0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
64d0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
64e0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
64f0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
6500: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
6510: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
6520: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
6530: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
6540: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
6550: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
6560: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
6570: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
6580: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
6590: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
65a0: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
65b0: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
65c0: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
65d0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
65e0: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
65f0: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
6600: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
6610: 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20  onflicts..**.** 
6620: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
6630: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
6640: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
6650: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
6660: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
6670: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
6680: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
6690: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
66a0: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
66b0: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
66c0: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
66d0: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
66e0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
66f0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6700: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
6710: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
6720: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
6730: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
6740: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
6750: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
6760: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
6770: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
6780: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6790: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
67a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
67b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
67c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
67d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
67e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
67f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
6800: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6810: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
6820: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6830: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
6840: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6850: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6860: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
6870: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6880: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
6890: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
68a0: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
68b0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
68c0: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
68d0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
68e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
68f0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6900: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
6910: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
6920: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6930: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6940: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
6950: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
6960: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
6970: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
6980: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
6990: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
69a0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
69b0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
69c0: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
69d0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
69e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
69f0: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
6a00: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
6a10: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
6a20: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6a30: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
6a40: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
6a50: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
6a60: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
6a70: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
6a80: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
6a90: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6aa0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
6ab0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6ac0: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
6ad0: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
6ae0: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
6af0: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
6b00: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
6b10: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
6b20: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
6b30: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f  hods sqlite3_io_
6b40: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
6b50: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6b60: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  ds {.  int iVers
6b70: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  ion;.  int (*xCl
6b80: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ose)(sqlite3_fil
6b90: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  e*);.  int (*xRe
6ba0: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ad)(sqlite3_file
6bb0: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  *, void*, int iA
6bc0: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
6bd0: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
6be0: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65  (*xWrite)(sqlite
6bf0: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76  3_file*, const v
6c00: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
6c10: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
6c20: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54  fst);.  int (*xT
6c30: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33  runcate)(sqlite3
6c40: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
6c50: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69  int64 size);.  i
6c60: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
6c70: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66  te3_file*, int f
6c80: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
6c90: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65  FileSize)(sqlite
6ca0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
6cb0: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a  _int64 *pSize);.
6cc0: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73    int (*xLock)(s
6cd0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
6ce0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c  t);.  int (*xUnl
6cf0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
6d00: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
6d10: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  (*xCheckReserved
6d20: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
6d30: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  le*, int *pResOu
6d40: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  t);.  int (*xFil
6d50: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
6d60: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
6d70: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
6d80: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
6d90: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6da0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
6db0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
6dc0: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
6dd0: 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  );.  /* Addition
6de0: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
6df0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
6e00: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
6e10: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6e20: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
6e30: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20  Control Opcodes 
6e40: 7b 46 31 31 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F11310}.**.** T
6e50: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
6e60: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
6e70: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
6e80: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
6e90: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
6ea0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
6eb0: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
6ec0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
6ed0: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
6ee0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
6ef0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
6f00: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
6f10: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
6f20: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
6f30: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
6f40: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
6f50: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
6f60: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
6f70: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
6f80: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
6f90: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
6fa0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
6fb0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
6fc0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
6fd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6fe0: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
6ff0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7000: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
7010: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
7020: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
7030: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
7040: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
7050: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
7060: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
7070: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
7080: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
7090: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
70a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
70b0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
70c0: 45 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a  E        1../*.*
70d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
70e0: 78 20 48 61 6e 64 6c 65 20 7b 46 31 37 31 31 30  x Handle {F17110
70f0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  }.**.** The mute
7100: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
7110: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
7120: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
7130: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
7140: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
7150: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
7160: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
7170: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
7180: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
7190: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
71a0: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
71b0: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
71c0: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
71d0: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
71e0: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
71f0: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
7200: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
7210: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
7220: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
7230: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7240: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
7250: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
7260: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7270: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b  terface Object {
7280: 46 31 31 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e  F11140}.**.** An
7290: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
72a0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
72b0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
72c0: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
72d0: 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20  n.** the SQLite 
72e0: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64  core and the und
72f0: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
7300: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22  g system.  The "
7310: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  vfs".** in the n
7320: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63  ame of the objec
7330: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69  t stands for "vi
7340: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
7350: 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  m"..**.** The va
7360: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
7370: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
7380: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
7390: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
73a0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
73b0: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
73c0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
73d0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
73e0: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
73f0: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
7400: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
7410: 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
7420: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20   szOsFile field 
7430: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
7440: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73  he subclassed [s
7450: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20  qlite3_file].** 
7460: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62  structure used b
7470: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50  y this VFS.  mxP
7480: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d  athname is the m
7490: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
74a0: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69  .** a pathname i
74b0: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a  n this VFS..**.*
74c0: 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c  * Registered sql
74d0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73  ite3_vfs objects
74e0: 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c   are kept on a l
74f0: 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65  inked list forme
7500: 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78  d by.** the pNex
7510: 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  t pointer.  The 
7520: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67  [sqlite3_vfs_reg
7530: 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20  ister()].** and 
7540: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72  [sqlite3_vfs_unr
7550: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72  egister()] inter
7560: 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69  faces manage thi
7570: 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74  s list.** in a t
7580: 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20  hread-safe way. 
7590: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
75a0: 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66  s_find()] interf
75b0: 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20  ace.** searches 
75c0: 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20  the list..**.** 
75d0: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
75e0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
75f0: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
7600: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
7610: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
7620: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
7630: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
7640: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
7650: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
7660: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
7670: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
7680: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
7690: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
76a0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
76b0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
76c0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
76d0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
76e0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
76f0: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
7700: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
7710: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
7720: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
7730: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
7740: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
7750: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
7760: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
7770: 2a 20 7b 46 31 31 31 34 31 7d 20 53 51 4c 69 74  * {F11141} SQLit
7780: 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65  e will guarantee
7790: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
77a0: 61 6d 65 20 73 74 72 69 6e 67 20 70 61 73 73 65  ame string passe
77b0: 64 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e 28 29 20  d to.** xOpen() 
77c0: 69 73 20 61 20 66 75 6c 6c 20 70 61 74 68 6e 61  is a full pathna
77d0: 6d 65 20 61 73 20 67 65 6e 65 72 61 74 65 64 20  me as generated 
77e0: 62 79 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  by xFullPathname
77f0: 28 29 20 61 6e 64 0a 2a 2a 20 74 68 61 74 20 74  () and.** that t
7800: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
7810: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
7820: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
7830: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
7840: 64 2e 20 20 7b 45 4e 44 7d 20 53 6f 20 74 68 65  d.  {END} So the
7850: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7860: 63 61 6e 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  can store a poin
7870: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
7880: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
7890: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
78a0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
78b0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 0a  some reason..**.
78c0: 2a 2a 20 7b 46 31 31 31 34 32 7d 20 54 68 65 20  ** {F11142} The 
78d0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
78e0: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
78f0: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
7900: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
7910: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
7920: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
7930: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
7940: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
7950: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
7960: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
7970: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
7980: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
7990: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
79a0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
79b0: 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e 44 7d  N_CREATE]. {END}
79c0: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
79d0: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
79e0: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
79f0: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
7a00: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
7a10: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
7a20: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
7a30: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
7a40: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
7a50: 7b 46 31 31 31 34 33 7d 20 53 51 4c 69 74 65 20  {F11143} SQLite 
7a60: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
7a70: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
7a80: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
7a90: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
7aa0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
7ab0: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
7ac0: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
7ad0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
7ae0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
7af0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7b00: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
7b10: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
7b20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
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 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_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 52   [SQLITE_OPEN_TR
7b70: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
7b80: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
7b90: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
7ba0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
7bb0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
7bc0: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e  AL].** </ul> {EN
7bd0: 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  D}.**.** The fil
7be0: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
7bf0: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
7c00: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
7c10: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
7c20: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
7c30: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
7c40: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
7c50: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
7c60: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
7c70: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
7c80: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
7c90: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
7ca0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
7cb0: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
7cc0: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
7cd0: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
7ce0: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
7cf0: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
7d00: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
7d10: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
7d20: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
7d30: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
7d40: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
7d50: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
7d60: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
7d70: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
7d80: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
7d90: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
7da0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
7db0: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
7dc0: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
7dd0: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
7de0: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
7df0: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
7e00: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
7e10: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
7e20: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
7e30: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
7e40: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
7e50: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
7e60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7e70: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
7e80: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
7e90: 20 7b 46 31 31 31 34 35 7d 20 54 68 65 20 5b 53   {F11145} The [S
7ea0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
7eb0: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
7ec0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
7ed0: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
7ee0: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
7ef0: 6f 73 65 64 2e 20 20 7b 46 31 31 31 34 36 7d 20  osed.  {F11146} 
7f00: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
7f10: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
7f20: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
7f30: 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 73  or TEMP  databas
7f40: 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64  es, journals and
7f50: 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73   for subjournals
7f60: 2e 0a 2a 2a 20 7b 46 31 31 31 34 37 7d 20 54 68  ..** {F11147} Th
7f70: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
7f80: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d  XCLUSIVE] flag m
7f90: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
7fa0: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a  ould be opened.*
7fb0: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
7fc0: 61 63 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c  access.  This fl
7fd0: 61 67 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c  ag is set for al
7fe0: 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a  l files except.*
7ff0: 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64  * for the main d
8000: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 7b 45  atabase file. {E
8010: 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34  ND}.**.** {F1114
8020: 38 7d 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  8} At least szOs
8030: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
8040: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
8050: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
8060: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
8070: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
8080: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
8090: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
80a0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
80b0: 20 7b 45 4e 44 7d 20 20 54 68 65 20 78 4f 70 65   {END}  The xOpe
80c0: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
80d0: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
80e0: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
80f0: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
8100: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a  ust fill it in..
8110: 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34 39 7d 20 54  **.** {F11149} T
8120: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8130: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
8140: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
8150: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
8160: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
8170: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
8180: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
8190: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
81a0: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
81b0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
81c0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
81d0: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
81e0: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
81f0: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
8200: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
8210: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 7b  ast readable.  {
8220: 45 4e 44 7d 20 54 68 65 20 66 69 6c 65 20 63 61  END} The file ca
8230: 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74  n be a.** direct
8240: 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31  ory..**.** {F111
8250: 35 30 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  50} SQLite will 
8260: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
8270: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
8280: 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
8290: 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
82a0: 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
82b0: 6d 65 2e 20 7b 46 31 31 31 35 31 7d 20 54 68 65  me. {F11151} The
82c0: 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74   exact size of t
82d0: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
82e0: 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73  .** is also pass
82f0: 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65  ed as a paramete
8300: 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f  r to both  metho
8310: 64 73 2e 20 7b 45 4e 44 7d 20 49 66 20 74 68 65  ds. {END} If the
8320: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
8330: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  * is not large e
8340: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43  nough, [SQLITE_C
8350: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20  ANTOPEN] should 
8360: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e  be returned. Sin
8370: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61  ce this is.** ha
8380: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
8390: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
83a0: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61  , vfs implementa
83b0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64  tions should end
83c0: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76  eavor.** to prev
83d0: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
83e0: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  ing mxPathname t
83f0: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
8400: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
8410: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
8420: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
8430: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
8440: 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
8450: 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  * are not strict
8460: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
8470: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
8480: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
8490: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
84a0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
84b0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
84c0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
84d0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
84e0: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
84f0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
8500: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
8510: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
8520: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
8530: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
8540: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
8550: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
8560: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
8570: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
8580: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
8590: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
85a0: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
85b0: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
85c0: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
85d0: 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20  nds given.  The 
85e0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a  xCurrentTime().*
85f0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
8600: 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75   a Julian Day Nu
8610: 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72  mber for the cur
8620: 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69  rent date and ti
8630: 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  me..*/.typedef s
8640: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
8650: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73  s sqlite3_vfs;.s
8660: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
8670: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
8680: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
8690: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
86a0: 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  ion number */.  
86b0: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
86c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
86d0: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
86e0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
86f0: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
8700: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
8710: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
8720: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
8730: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
8740: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
8750: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
8760: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
8770: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
8780: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
8790: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
87a0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
87b0: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
87c0: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
87d0: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
87e0: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
87f0: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
8800: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
8810: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
8820: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
8830: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
8840: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
8850: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
8860: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
8870: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
8880: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
8890: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
88a0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
88b0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
88c0: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
88d0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
88e0: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
88f0: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
8900: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
8910: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
8920: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
8930: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
8940: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8950: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
8960: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
8970: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
8980: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
8990: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
89a0: 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  g);.  void *(*xD
89b0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
89c0: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
89d0: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a  char *zSymbol);.
89e0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
89f0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
8a00: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
8a10: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
8a20: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
8a30: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
8a40: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
8a50: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
8a60: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
8a70: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
8a80: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
8a90: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
8aa0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
8ab0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
8ac0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
8ad0: 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66  r *);.  /* New f
8ae0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
8af0: 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20  ended in figure 
8b00: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
8b10: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
8b20: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
8b30: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
8b40: 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a  happens. */.};..
8b50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8b60: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
8b70: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
8b80: 20 7b 46 31 31 31 39 30 7d 0a 2a 2a 0a 2a 2a 20   {F11190}.**.** 
8b90: 7b 46 31 31 31 39 31 7d 20 54 68 65 73 65 20 69  {F11191} These i
8ba0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
8bb0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
8bc0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
8bd0: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
8be0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
8bf0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
8c00: 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20   object. {END}  
8c10: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
8c20: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70  * what kind of p
8c30: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78  ermissions the x
8c40: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73  Access method is
8c50: 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e  .** looking for.
8c60: 20 20 7b 46 31 31 31 39 32 7d 20 57 69 74 68 20    {F11192} With 
8c70: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
8c80: 58 49 53 54 53 5d 2c 20 74 68 65 20 78 41 63 63  XISTS], the xAcc
8c90: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
8ca0: 6d 70 6c 79 20 63 68 65 63 6b 73 20 74 6f 20 73  mply checks to s
8cb0: 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 20 65  ee if the file e
8cc0: 78 69 73 74 73 2e 20 7b 46 31 31 31 39 33 7d 20  xists. {F11193} 
8cd0: 57 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 41  With.** SQLITE_A
8ce0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
8cf0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
8d00: 68 6f 64 20 63 68 65 63 6b 73 20 74 6f 20 73 65  hod checks to se
8d10: 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 6c 65  e.** if the file
8d20: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
8d30: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 20  e and writable. 
8d40: 20 7b 46 31 31 31 39 34 7d 20 57 69 74 68 0a 2a   {F11194} With.*
8d50: 2a 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  * SQLITE_ACCESS_
8d60: 52 45 41 44 20 74 68 65 20 78 41 63 63 65 73 73  READ the xAccess
8d70: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
8d80: 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20  s to see if the 
8d90: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
8da0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
8db0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
8dc0: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
8dd0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
8de0: 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65  DWRITE 1.#define
8df0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
8e00: 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a  EAD      2../*.*
8e10: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
8e20: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
8e30: 65 20 4c 69 62 72 61 72 79 20 7b 46 31 30 31 33  e Library {F1013
8e40: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
8e50: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8e60: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
8e70: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
8e80: 69 74 65 20 6c 69 62 72 61 72 79 20 70 72 69 6f  ite library prio
8e90: 72 20 74 6f 20 75 73 65 2e 20 20 54 68 65 20 73  r to use.  The s
8ea0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
8eb0: 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61  ) routine.** dea
8ec0: 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73  llocates any res
8ed0: 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65  ources that were
8ee0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
8ef0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
8f00: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  ()..**.** A call
8f10: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
8f20: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
8f30: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
8f40: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
8f50: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
8f60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
8f70: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
8f80: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
8f90: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
8fa0: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
8fb0: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
8fc0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8fd0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
8fe0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
8ff0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
9000: 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e  down().  Only an
9010: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
9020: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
9030: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
9040: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
9050: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
9060: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
9070: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 20 20 49 6e  less no-ops.  In
9080: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a   other words,.**
9090: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   the sqlite3_ini
90a0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
90b0: 65 20 6d 61 79 20 62 65 20 63 61 6c 6c 65 64 20  e may be called 
90c0: 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 0a 2a  multiple times.*
90d0: 2a 20 77 69 74 68 6f 75 74 20 63 6f 6e 73 65 71  * without conseq
90e0: 75 65 6e 63 65 2e 20 20 53 65 63 6f 6e 64 20 61  uence.  Second a
90f0: 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 65 76  nd subsequent ev
9100: 61 6c 75 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20  aluations of.** 
9110: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9120: 7a 65 28 29 20 61 72 65 20 6e 6f 2d 6f 70 73 2e  ze() are no-ops.
9130: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e    The sqlite3_in
9140: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
9150: 6e 65 0a 2a 2a 20 6f 6e 6c 79 20 77 6f 72 6b 73  ne.** only works
9160: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
9170: 69 74 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72  it is called for
9180: 20 61 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 74   a process, or t
9190: 68 65 20 66 69 72 73 74 0a 2a 2a 20 74 69 6d 65  he first.** time
91a0: 20 69 74 20 69 73 20 63 61 6c 6c 65 64 20 61 66   it is called af
91b0: 74 65 72 20 73 71 6c 69 74 65 33 5f 73 68 75 74  ter sqlite3_shut
91c0: 64 6f 77 6e 28 29 2e 20 20 49 6e 20 61 6c 6c 20  down().  In all 
91d0: 6f 74 68 65 72 20 63 61 73 65 73 2c 0a 2a 2a 20  other cases,.** 
91e0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
91f0: 7a 65 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ze() returns SQL
9200: 49 54 45 5f 4f 4b 20 77 69 74 68 6f 75 74 20 64  ITE_OK without d
9210: 6f 69 6e 67 20 61 6e 79 20 72 65 61 6c 20 77 6f  oing any real wo
9220: 72 6b 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  rk..**.** Among 
9230: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71  other things, sq
9240: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9250: 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a  () shall invoke.
9260: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
9270: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
9280: 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  , sqlite3_shutdo
9290: 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e  wn().** shall in
92a0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
92b0: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  end()..**.** The
92c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
92d0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
92e0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20  turns SQLITE_OK 
92f0: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49  on success..** I
9300: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
9310: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
9320: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
9330: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
9340: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
9350: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
9360: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
9370: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
9380: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
9390: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
93a0: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
93b0: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 53 51 4c  ] other than SQL
93c0: 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 54 68  ITE_OK..**.** Th
93d0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
93e0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
93f0: 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
9400: 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
9410: 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
9420: 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
9430: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
9440: 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
9450: 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
9460: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9470: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
9480: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
9490: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
94a0: 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
94b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
94c0: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
94d0: 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
94e0: 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
94f0: 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
9500: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
9510: 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
9520: 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
9530: 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
9540: 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51    However, if SQ
9550: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
9560: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
9570: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 0a 2a  _OMIT_AUTOINIT.*
9580: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
9590: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
95a0: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
95b0: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
95c0: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
95d0: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
95e0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
95f0: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
9600: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
9610: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
9620: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
9630: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
9640: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
9650: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
9660: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
9670: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
9680: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
9690: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
96a0: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
96b0: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
96c0: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
96d0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
96e0: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
96f0: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
9700: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
9710: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
9720: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
9730: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
9740: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
9750: 69 74 68 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  ith SQLITE_OMIT_
9760: 41 55 54 4f 49 4e 49 54 20 6d 69 67 68 74 20 62  AUTOINIT might b
9770: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
9780: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
9790: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
97a0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
97b0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
97c0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
97d0: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
97e0: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
97f0: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
9800: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
9810: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
9820: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
9830: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
9840: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
9850: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
9860: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
9870: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
9880: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
9890: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
98a0: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
98b0: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
98c0: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
98d0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
98e0: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
98f0: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
9900: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
9910: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
9920: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
9930: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
9940: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
9950: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
9960: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
9970: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
9980: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
9990: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
99a0: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
99b0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
99c0: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
99d0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
99e0: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
99f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9a00: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
9a10: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
9a20: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9a30: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
9a40: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
9a50: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
9a60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
9a70: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
9a80: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
9a90: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
9aa0: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
9ab0: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
9ac0: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
9ad0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
9ae0: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
9af0: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
9b00: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
9b10: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
9b20: 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77  for unix, window
9b30: 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57  s, or os/2..** W
9b40: 68 65 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f 74  hen built for ot
9b50: 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 20 28 75  her platforms (u
9b60: 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  sing the SQLITE_
9b70: 4f 53 5f 4f 54 48 45 52 3d 31 20 63 6f 6d 70 69  OS_OTHER=1 compi
9b80: 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
9b90: 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
9ba0: 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
9bb0: 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
9bc0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
9bd0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9be0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
9bf0: 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
9c00: 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
9c10: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
9c20: 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
9c30: 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
9c40: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
9c50: 75 73 74 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ust return SQLIT
9c60: 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20  E_OK on success 
9c70: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
9c80: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
9c90: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
9ca0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
9cb0: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e  ialize(void);.in
9cc0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
9cd0: 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  wn(void);.int sq
9ce0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
9cf0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
9d00: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
9d10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9d20: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
9d30: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b  SQLite Library {
9d40: 46 31 30 31 34 35 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10145}.**.** Th
9d50: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
9d60: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
9d70: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
9d80: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
9d90: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
9da0: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
9db0: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
9dc0: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
9dd0: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
9de0: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
9df0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
9e00: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
9e10: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
9e20: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
9e30: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
9e40: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
9e50: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
9e60: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
9e70: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
9e80: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
9e90: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
9ea0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
9eb0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
9ec0: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
9ed0: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
9ee0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
9ef0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
9f00: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
9f10: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
9f20: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
9f30: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
9f40: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
9f50: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
9f60: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
9f70: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
9f80: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
9f90: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
9fa0: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
9fb0: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
9fc0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9fd0: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
9fe0: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
9ff0: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
a000: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
a010: 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  hat sqlite3_conf
a020: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
a030: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
a040: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
a050: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
a060: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
a070: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a080: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
a090: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
a0a0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
a0b0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
a0c0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
a0d0: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
a0e0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
a0f0: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
a100: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
a110: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
a120: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
a130: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
a140: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
a150: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
a160: 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
a170: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
a180: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
a190: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
a1a0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
a1b0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63  ..**.** When a c
a1c0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
a1d0: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
a1e0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
a1f0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  urns SQLITE_OK..
a200: 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  ** If the option
a210: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
a220: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
a230: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
a240: 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
a250: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
a260: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
a270: 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
a280: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
a290: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
a2a0: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
a2b0: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
a2c0: 69 6e 65 73 20 7b 46 31 30 31 35 35 7d 0a 2a 2a  ines {F10155}.**
a2d0: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
a2e0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
a2f0: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
a300: 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
a310: 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
a320: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
a330: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
a340: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
a350: 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
a360: 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
a370: 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
a380: 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
a390: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
a3a0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
a3b0: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
a3c0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
a3d0: 63 6f 6e 66 69 67 5d 20 77 68 65 6e 20 74 68 65  config] when the
a3e0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
a3f0: 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
a400: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
a410: 43 5d 2e 20 20 42 79 20 63 72 65 61 74 69 6e 67  C].  By creating
a420: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
a430: 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
a440: 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
a450: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
a460: 5d 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  ] during configu
a470: 72 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70  ration, an.** ap
a480: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
a490: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
a4a0: 74 69 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  tive memory allo
a4b0: 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
a4c0: 0a 2a 2a 20 66 6f 72 20 53 51 4c 69 74 65 20 74  .** for SQLite t
a4d0: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
a4e0: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
a4f0: 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
a500: 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
a510: 65 20 63 6f 6d 65 73 20 77 69 74 68 20 61 20 62  e comes with a b
a520: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
a530: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 69 73  llocator that is
a540: 0a 2a 2a 20 70 65 72 66 65 63 74 6c 79 20 61 64  .** perfectly ad
a550: 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
a560: 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
a570: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
a580: 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
a590: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
a5a0: 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
a5b0: 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
a5c0: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
a5d0: 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
a5e0: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
a5f0: 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
a600: 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
a610: 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
a620: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
a630: 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
a640: 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
a650: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
a660: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
a670: 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
a680: 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
a690: 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
a6a0: 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
a6b0: 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
a6c0: 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
a6d0: 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
a6e0: 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
a6f0: 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c  .** The xMalloc,
a700: 20 78 46 72 65 65 2c 20 61 6e 64 20 78 52 65 61   xFree, and xRea
a710: 6c 6c 6f 63 20 6d 65 74 68 6f 64 73 20 73 68 6f  lloc methods sho
a720: 75 6c 64 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  uld work like th
a730: 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 66  e.** malloc(), f
a740: 72 65 65 28 29 2c 20 61 6e 64 20 72 65 61 6c 6c  ree(), and reall
a750: 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  oc() functions f
a760: 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
a770: 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
a780: 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
a790: 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
a7a0: 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
a7b0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
a7c0: 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
a7d0: 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
a7e0: 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
a7f0: 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
a800: 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
a810: 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
a820: 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
a830: 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
a840: 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
a850: 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
a860: 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
a870: 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
a880: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
a890: 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
a8a0: 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
a8b0: 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
a8c0: 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
a8d0: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
a8e0: 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
a8f0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
a900: 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
a910: 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
a920: 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
a930: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
a940: 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
a950: 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
a960: 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20  wer of 2..**.** 
a970: 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
a980: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
a990: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
a9a0: 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65  r.  (For example
a9b0: 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c  ,.** it might al
a9c0: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69  locate any requi
a9d0: 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e  re mutexes or in
a9e0: 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61  itialize interna
a9f0: 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74  l data.** struct
aa00: 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74  ures.  The xShut
aa10: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69  down method is i
aa20: 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74  nvoked (indirect
aa30: 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ly) by.** [sqlit
aa40: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61  e3_shutdown()] a
aa50: 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f  nd should deallo
aa60: 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63  cate any resourc
aa70: 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62  es acquired.** b
aa80: 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41  y xInit.  The pA
aa90: 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69  ppData pointer i
aaa0: 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e  s used as the on
aab0: 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  ly parameter to.
aac0: 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68  ** xInit and xSh
aad0: 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64  utdown..*/.typed
aae0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
aaf0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
ab00: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
ab10: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
ab20: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
ab30: 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
ab40: 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
ab50: 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
ab60: 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
ab70: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
ab80: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
ab90: 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
aba0: 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
abb0: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
abc0: 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
abd0: 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
abe0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
abf0: 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
ac00: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
ac10: 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
ac20: 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
ac30: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
ac40: 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
ac50: 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
ac60: 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
ac70: 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
ac80: 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
ac90: 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
aca0: 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
acb0: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
acc0: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
acd0: 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
ace0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
acf0: 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
ad00: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
ad10: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
ad20: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
ad30: 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
ad40: 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
ad50: 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
ad60: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
ad70: 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
ad80: 6e 20 4f 70 74 69 6f 6e 73 20 7b 46 31 30 31 36  n Options {F1016
ad90: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  0}.**.** These c
ada0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
adb0: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
adc0: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
add0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
ade0: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
adf0: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
ae00: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
ae10: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
ae20: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
ae30: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
ae40: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
ae50: 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
ae60: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
ae70: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
ae80: 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20  s option.  This 
ae90: 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a  option disables.
aea0: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
aeb0: 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
aec0: 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
aed0: 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
aee0: 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
aef0: 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64  ngle thread.</dd
af00: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
af10: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
af20: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
af30: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
af40: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
af50: 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f   option.  This o
af60: 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a  ption disables.*
af70: 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
af80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
af90: 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
afa0: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
afb0: 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
afc0: 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
afd0: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
afe0: 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
aff0: 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
b000: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
b010: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
b020: 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
b030: 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
b040: 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
b050: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
b060: 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
b070: 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
b080: 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2e 3c  ** environment.<
b090: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
b0a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
b0b0: 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
b0c0: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
b0d0: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
b0e0: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73  is option.  This
b0f0: 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
b100: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
b110: 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
b120: 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
b130: 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
b140: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
b150: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
b160: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
b170: 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
b180: 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
b190: 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
b1a0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
b1b0: 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44  ** SQLITE_THREAD
b1c0: 53 41 46 45 3d 31 29 20 74 68 65 20 53 51 4c 69  SAFE=1) the SQLi
b1d0: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
b1e0: 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65  itself serialize
b1f0: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64   access.** to [d
b200: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
b210: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
b220: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73  ed statements] s
b230: 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70  o that the.** ap
b240: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65  plication is fre
b250: 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  e to use the sam
b260: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
b270: 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a  ection] or the.*
b280: 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  * same [prepared
b290: 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64   statement] in d
b2a0: 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73  ifferent threads
b2b0: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
b2c0: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
b2d0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
b2e0: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
b2f0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
b300: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
b310: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
b320: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
b330: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
b340: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
b350: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
b360: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
b370: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
b380: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
b390: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
b3a0: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
b3b0: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
b3c0: 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
b3d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b3e0: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
b3f0: 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  nto SQLite.</dd>
b400: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
b410: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
b420: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OC</dt>.** <dd>T
b430: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
b440: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
b450: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
b460: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
b470: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
b480: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
b490: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
b4a0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
b4b0: 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
b4c0: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
b4d0: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
b4e0: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
b4f0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
b500: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73  outines..** This
b510: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
b520: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
b530: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
b540: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
b550: 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
b560: 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
b570: 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
b580: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
b590: 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
b5a0: 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
b5b0: 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e  or example.</dd>
b5c0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
b5d0: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
b5e0: 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  US</dt>.** <dd>T
b5f0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
b600: 20 73 69 6e 67 6c 65 20 62 6f 6f 6c 65 61 6e 20   single boolean 
b610: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 65  argument which e
b620: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
b630: 65 73 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 65 63  es.** the collec
b640: 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61  tion of memory a
b650: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
b660: 74 69 63 73 2e 20 20 57 68 65 6e 20 64 69 73 61  tics.  When disa
b670: 62 6c 65 64 2c 20 74 68 65 0a 2a 2a 20 66 6f 6c  bled, the.** fol
b680: 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
b690: 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
b6a0: 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
b6b0: 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
b6c0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
b6d0: 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
b6e0: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
b6f0: 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
b700: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
b710: 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
b720: 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c  _limit()].**   <
b730: 6c 69 3e 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  li> sqlite3_memo
b740: 72 79 5f 73 74 61 74 75 73 28 29 0a 2a 2a 20 20  ry_status().**  
b750: 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a   </ul>.** </dd>.
b760: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
b770: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c  _CONFIG_SCRATCH<
b780: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
b790: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
b7a0: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
b7b0: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
b7c0: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
b7d0: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
b7e0: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
b7f0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
b800: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
b810: 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a  e memory, the.**
b820: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
b830: 72 61 74 63 68 20 62 75 66 66 65 72 20 28 73 7a  ratch buffer (sz
b840: 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
b850: 72 20 6f 66 20 62 75 66 66 65 72 73 20 28 4e 29  r of buffers (N)
b860: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
b870: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
b880: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20  multiple of 16. 
b890: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
b8a0: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
b8b0: 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
b8c0: 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
b8d0: 28 73 7a 2b 34 29 2a 4e 20 62 79 74 65 73 20 6f  (sz+4)*N bytes o
b8e0: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c  f memory..** SQL
b8f0: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
b900: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63  more than one sc
b910: 72 61 74 63 68 20 62 75 66 66 65 72 20 61 74 20  ratch buffer at 
b920: 6f 6e 63 65 20 70 65 72 20 74 68 72 65 61 64 2c  once per thread,
b930: 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   so.** N should 
b940: 62 65 20 73 65 74 20 74 6f 20 74 68 65 20 65 78  be set to the ex
b950: 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e  pected maximum n
b960: 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73  umber of threads
b970: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72  .  The sz.** par
b980: 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
b990: 20 36 20 74 69 6d 65 73 20 74 68 65 20 73 69 7a   6 times the siz
b9a0: 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
b9b0: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
b9c0: 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20  ize..** Scratch 
b9d0: 62 75 66 66 65 72 73 20 61 72 65 20 75 73 65 64  buffers are used
b9e0: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
b9f0: 62 74 72 65 65 20 62 61 6c 61 6e 63 65 20 6f 70  btree balance op
ba00: 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20  eration.  If.** 
ba10: 54 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63  The btree balanc
ba20: 65 72 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  er needs additio
ba30: 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  nal memory beyon
ba40: 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
ba50: 65 64 20 62 79 0a 2a 2a 20 73 63 72 61 74 63 68  ed by.** scratch
ba60: 20 62 75 66 66 65 72 73 20 6f 72 20 69 66 20 6e   buffers or if n
ba70: 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  o scratch buffer
ba80: 20 73 70 61 63 65 20 69 73 20 73 70 65 63 69 66   space is specif
ba90: 69 65 64 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ied, then SQLite
baa0: 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  .** goes to [sql
bab0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74  ite3_malloc()] t
bac0: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
bad0: 6f 72 79 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64  ory it needs.</d
bae0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
baf0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
bb00: 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
bb10: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  >This option spe
bb20: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
bb30: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
bb40: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
bb50: 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74  e for.** the dat
bb60: 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
bb70: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
bb80: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20  ee arguments: A 
bb90: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
bba0: 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
bbb0: 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
bbc0: 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
bbd0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
bbe0: 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
bbf0: 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73   sz argument mus
bc00: 74 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20  t be a power of 
bc10: 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
bc20: 61 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65 20  and 32768.  The 
bc30: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
bc40: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
bc50: 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
bc60: 6f 66 20 61 74 20 6c 65 61 73 74 20 28 73 7a 2b  of at least (sz+
bc70: 34 29 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  4)*N bytes of me
bc80: 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  mory..** SQLite 
bc90: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
bca0: 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
bcb0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
bcc0: 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
bcd0: 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
bce0: 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
bcf0: 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
bd00: 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
bd10: 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
bd20: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
bd30: 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
bd40: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
bd50: 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
bd60: 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
bd70: 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
bd80: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
bd90: 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
bda0: 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
bdb0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bdc0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
bdd0: 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AP</dt>.** <dd>T
bde0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
bdf0: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
be00: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
be10: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
be20: 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
be30: 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
be40: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
be50: 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
be60: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
be70: 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
be80: 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
be90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
bea0: 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
beb0: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
bec0: 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65  uments: A pointe
bed0: 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
bee0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
bef0: 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  * bytes in the m
bf00: 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
bf10: 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
bf20: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20  location size.  
bf30: 57 68 65 6e 0a 2a 2a 20 74 68 69 73 20 63 6f 6e  When.** this con
bf40: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
bf50: 6e 20 69 73 20 75 73 65 64 2c 20 53 51 4c 69 74  n is used, SQLit
bf60: 65 20 6e 65 76 65 72 20 63 61 6c 6c 73 20 74 68  e never calls th
bf70: 65 20 73 79 73 74 65 6d 0a 2a 2a 20 6d 61 6c 6c  e system.** mall
bf80: 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
bf90: 69 6f 6e 20 62 75 74 20 69 6e 73 74 65 61 64 20  ion but instead 
bfa0: 75 73 65 73 20 74 68 65 20 73 75 70 70 6c 69 65  uses the supplie
bfb0: 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a  d memory buffer.
bfc0: 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20 61 6c  ** to satisfy al
bfd0: 6c 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  l [sqlite3_mallo
bfe0: 63 28 29 5d 20 72 65 71 75 65 73 74 73 2e 3c 2f  c()] requests.</
bff0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
c000: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
c010: 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  X</dt>.** <dd>Th
c020: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
c030: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
c040: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
c050: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
c060: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
c070: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
c080: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
c090: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
c0a0: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
c0b0: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
c0c0: 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
c0d0: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
c0e0: 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
c0f0: 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
c100: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64   into SQLite.</d
c110: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c120: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
c130: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
c140: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
c150: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
c160: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
c170: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
c180: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
c190: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
c1a0: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
c1b0: 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
c1c0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
c1d0: 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
c1e0: 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
c1f0: 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
c200: 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
c210: 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70  ines..** This op
c220: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
c230: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
c240: 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
c250: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
c260: 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
c270: 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
c280: 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
c290: 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
c2a0: 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
c2b0: 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
c2c0: 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ple.</dd>.**.** 
c2d0: 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
c2e0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
c2f0: 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
c300: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
c310: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c320: 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
c330: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
c340: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
c350: 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
c360: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
c370: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c380: 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
c390: 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
c3a0: 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
c3b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
c3c0: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
c3d0: 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
c3e0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
c3f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
c400: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
c410: 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
c420: 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
c430: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
c440: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
c450: 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
c460: 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
c470: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
c480: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
c490: 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
c4a0: 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
c4b0: 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
c4c0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
c4d0: 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
c4e0: 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
c4f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
c500: 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
c510: 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
c520: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
c530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
c540: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
c550: 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
c560: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
c570: 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  ods* */../*.** C
c580: 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
c590: 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
c5a0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
c5b0: 20 7b 46 31 32 32 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F12200}.**.** 
c5c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
c5d0: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
c5e0: 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
c5f0: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
c600: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
c610: 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
c620: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
c630: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
c640: 4c 69 74 65 2e 0a 2a 2a 20 54 68 65 20 65 78 74  Lite..** The ext
c650: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
c660: 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
c670: 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
c680: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d  istorical.** com
c690: 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73 69  patibility consi
c6a0: 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  derations..**.**
c6b0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
c6c0: 2a 2a 20 7b 46 31 32 32 30 31 7d 20 45 61 63 68  ** {F12201} Each
c6d0: 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63   new [database c
c6e0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61 6c 6c  onnection] shall
c6f0: 20 68 61 76 65 20 74 68 65 0a 2a 2a 20 20 20 20   have the.**    
c700: 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20        [extended 
c710: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
c720: 61 74 75 72 65 20 64 69 73 61 62 6c 65 64 20 62  ature disabled b
c730: 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
c740: 20 7b 46 31 32 32 30 32 7d 20 54 68 65 20 5b 73   {F12202} The [s
c750: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
c760: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c 46  result_codes(D,F
c770: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
c780: 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20 20  ll enable.**    
c790: 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20        [extended 
c7a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 6f  result codes] fo
c7b0: 72 20 74 68 65 20 20 5b 64 61 74 61 62 61 73 65  r the  [database
c7c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
c7d0: 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68  *          if th
c7e0: 65 20 46 20 70 61 72 61 6d 65 74 65 72 20 69 73  e F parameter is
c7f0: 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62 6c   true, or disabl
c800: 65 20 74 68 65 6d 20 69 66 20 46 20 69 73 20 66  e them if F is f
c810: 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  alse..*/.int sql
c820: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
c830: 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
c840: 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
c850: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c860: 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
c870: 77 69 64 20 7b 46 31 32 32 32 30 7d 0a 2a 2a 0a  wid {F12220}.**.
c880: 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e  ** Each entry in
c890: 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65   an SQLite table
c8a0: 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
c8b0: 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
c8c0: 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
c8d0: 64 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54  d the "rowid". T
c8e0: 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
c8f0: 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
c900: 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
c910: 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
c920: 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
c930: 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
c940: 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
c950: 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
c960: 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
c970: 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
c980: 20 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65   If.** the table
c990: 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
c9a0: 20 74 79 70 65 20 49 4e 54 45 47 45 52 20 50 52   type INTEGER PR
c9b0: 49 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74  IMARY KEY then t
c9c0: 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
c9d0: 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
c9e0: 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
c9f0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
ca00: 20 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77   returns the row
ca10: 69 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  id of the most r
ca20: 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
ca30: 66 75 6c 20 49 4e 53 45 52 54 20 69 6e 74 6f 20  ful INSERT into 
ca40: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f  the database fro
ca50: 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  m the [database 
ca60: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69  connection].** i
ca70: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
ca80: 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 63  ment.  If no suc
ca90: 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 73 0a  cessful INSERTs.
caa0: 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
cab0: 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61  urred on that da
cac0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
cad0: 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  n, zero is retur
cae0: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ned..**.** If an
caf0: 20 49 4e 53 45 52 54 20 6f 63 63 75 72 73 20 77   INSERT occurs w
cb00: 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
cb10: 20 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20   then the rowid 
cb20: 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
cb30: 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e  ** row is return
cb40: 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
cb50: 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ne as long as th
cb60: 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e  e trigger is run
cb70: 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
cb80: 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65  e the trigger te
cb90: 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61  rminates, the va
cba0: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
cbb0: 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
cbc0: 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c  reverts to the l
cbd0: 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74  ast value insert
cbe0: 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  ed before the tr
cbf0: 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a  igger fired..**.
cc00: 2a 2a 20 41 6e 20 49 4e 53 45 52 54 20 74 68 61  ** An INSERT tha
cc10: 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
cc20: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
cc30: 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
cc40: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53  * successful INS
cc50: 45 52 54 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ERT and does not
cc60: 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
cc70: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
cc80: 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
cc90: 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
cca0: 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
ccb0: 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
ccc0: 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
ccd0: 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
cce0: 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
ccf0: 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
cd00: 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
cd10: 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
cd20: 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
cd30: 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52  ils.  When INSER
cd40: 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
cd50: 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
cd60: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
cd70: 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
cd80: 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
cd90: 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
cda0: 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
cdb0: 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
cdc0: 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
cdd0: 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
cde0: 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
cdf0: 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
ce00: 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
ce10: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
ce20: 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
ce30: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74  ace..**.** For t
ce40: 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
ce50: 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
ce60: 49 4e 53 45 52 54 20 69 73 20 63 6f 6e 73 69 64  INSERT is consid
ce70: 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
ce80: 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
ce90: 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
cea0: 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
ceb0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
cec0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 31  S:.**.** {F12221
ced0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  } The [sqlite3_l
cee0: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
cef0: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ()] function ret
cf00: 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 0a 2a  urns the rowid.*
cf10: 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
cf20: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  e most recent su
cf30: 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20  ccessful INSERT 
cf40: 70 65 72 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65  performed on the
cf50: 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
cf60: 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
cf70: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 77 69 74 68  ection] and with
cf80: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68  in the same or h
cf90: 69 67 68 65 72 20 6c 65 76 65 6c 0a 2a 2a 20 20  igher level.**  
cfa0: 20 20 20 20 20 20 20 20 74 72 69 67 67 65 72 20          trigger 
cfb0: 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f  context, or zero
cfc0: 20 69 66 20 74 68 65 72 65 20 68 61 76 65 20 62   if there have b
cfd0: 65 65 6e 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e  een no qualifyin
cfe0: 67 20 69 6e 73 65 72 74 73 2e 0a 2a 2a 0a 2a 2a  g inserts..**.**
cff0: 20 7b 46 31 32 32 32 33 7d 20 54 68 65 20 5b 73   {F12223} The [s
d000: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
d010: 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63  rt_rowid()] func
d020: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
d030: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 61 6d  .**          sam
d040: 65 20 76 61 6c 75 65 20 77 68 65 6e 20 63 61 6c  e value when cal
d050: 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
d060: 65 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  e trigger contex
d070: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d  t.**          im
d080: 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65  mediately before
d090: 20 61 6e 64 20 61 66 74 65 72 20 61 20 52 4f 4c   and after a ROL
d0a0: 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d  LBACK..**.** LIM
d0b0: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
d0c0: 7b 55 31 32 32 33 32 7d 20 49 66 20 61 20 73 65  {U12232} If a se
d0d0: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
d0e0: 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 49 4e 53  rforms a new INS
d0f0: 45 52 54 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  ERT on the same.
d100: 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61  **          data
d110: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
d120: 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
d130: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
d140: 6f 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20  owid()].**      
d150: 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20      function is 
d160: 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
d170: 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
d180: 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a  t insert rowid,.
d190: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
d1a0: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
d1b0: 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
d1c0: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
d1d0: 64 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20  d()] is.**      
d1e0: 20 20 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c      unpredictabl
d1f0: 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
d200: 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
d210: 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
d220: 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61 73 74  **          last
d230: 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a   insert rowid..*
d240: 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
d250: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
d260: 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
d270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
d280: 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
d290: 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
d2a0: 6f 64 69 66 69 65 64 20 7b 46 31 32 32 34 30 7d  odified {F12240}
d2b0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
d2c0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
d2d0: 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
d2e0: 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
d2f0: 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
d300: 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
d310: 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
d320: 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
d330: 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
d340: 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74  t.** on the [dat
d350: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d360: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  ] specified by t
d370: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
d380: 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e  er..** Only chan
d390: 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
d3a0: 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
d3b0: 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55  by the INSERT, U
d3c0: 50 44 41 54 45 2c 0a 2a 2a 20 6f 72 20 44 45 4c  PDATE,.** or DEL
d3d0: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
d3e0: 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69  e counted.  Auxi
d3f0: 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
d400: 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67  used by.** trigg
d410: 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ers are not coun
d420: 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71  ted. Use the [sq
d430: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
d440: 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a  ges()] function.
d450: 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  ** to find the t
d460: 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
d470: 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67  hanges including
d480: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
d490: 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a  by triggers..**.
d4a0: 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65  ** A "row change
d4b0: 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
d4c0: 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
d4d0: 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
d4e0: 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
d4f0: 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
d500: 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
d510: 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
d520: 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
d530: 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
d540: 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  f REPLACE constr
d550: 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
d560: 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
d570: 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
d580: 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 62  DROP TABLE, or b
d590: 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d  y any other.** m
d5a0: 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74  echanisms do not
d5b0: 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74   count as direct
d5c0: 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a   row changes..**
d5d0: 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63  .** A "trigger c
d5e0: 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f  ontext" is a sco
d5f0: 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20  pe of execution 
d600: 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a  that begins and.
d610: 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65  ** ends with the
d620: 20 73 63 72 69 70 74 20 6f 66 20 61 20 74 72 69   script of a tri
d630: 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20  gger.  Most SQL 
d640: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
d650: 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73  * evaluated outs
d660: 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67  ide of any trigg
d670: 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  er.  This is the
d680: 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20   "top level".** 
d690: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
d6a0: 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66    If a trigger f
d6b0: 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f  ires from the to
d6c0: 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65  p level, a.** ne
d6d0: 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
d6e0: 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72  t is entered for
d6f0: 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66   the duration of
d700: 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69   that one.** tri
d710: 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65  gger.  Subtrigge
d720: 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e  rs create subcon
d730: 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20  texts for their 
d740: 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  duration..**.** 
d750: 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
d760: 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
d770: 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
d780: 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a  ursively does.**
d790: 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65   not create a ne
d7a0: 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
d7b0: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  t..**.** This fu
d7c0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
d7d0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72  he number of dir
d7e0: 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  ect row changes 
d7f0: 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  in the.** most r
d800: 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
d810: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
d820: 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
d830: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69   the same.** tri
d840: 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
d850: 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 63  .** Thus, when c
d860: 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
d870: 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
d880: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
d890: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
d8a0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
d8b0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
d8c0: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
d8d0: 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
d8e0: 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
d8f0: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57  he top level.  W
d900: 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
d910: 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20  f a trigger,.** 
d920: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
d930: 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
d940: 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
d950: 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
d960: 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
d970: 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
d980: 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
d990: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
d9a0: 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
d9b0: 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
d9c0: 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
d9d0: 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77   trigger..** How
d9e0: 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72  ever, the number
d9f0: 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
da00: 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
da10: 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  es.** caused by 
da20: 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63  subtriggers sinc
da30: 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65  e those have the
da40: 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a  ir own context..
da50: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
da60: 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d  lements the comm
da70: 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  and "DELETE FROM
da80: 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20   table" without 
da90: 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a  a WHERE clause.*
daa0: 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e  * by dropping an
dab0: 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65  d recreating the
dac0: 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69   table.  (This i
dad0: 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68  s much faster th
dae0: 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f  an going.** thro
daf0: 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67  ugh and deleting
db00: 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d   individual elem
db10: 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61  ents from the ta
db20: 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f  ble.)  Because o
db30: 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69  f this.** optimi
db40: 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65  zation, the dele
db50: 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45  tions in "DELETE
db60: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65   FROM table" are
db70: 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73   not row changes
db80: 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74   and.** will not
db90: 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74   be counted by t
dba0: 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
dbb0: 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33  es() or [sqlite3
dbc0: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
dbd0: 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20  ].** functions, 
dbe0: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
dbf0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d  e number of elem
dc00: 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f  ents that were o
dc10: 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20  riginally.** in 
dc20: 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67  the table.  To g
dc30: 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63  et an accurate c
dc40: 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62  ount of the numb
dc50: 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74  er of rows delet
dc60: 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45  ed, use.** "DELE
dc70: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48  TE FROM table WH
dc80: 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a  ERE 1" instead..
dc90: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
dca0: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34 31 7d  :.**.** {F12241}
dcb0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   The [sqlite3_ch
dcc0: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
dcd0: 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 74  n shall return t
dce0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
dcf0: 20 20 20 20 20 20 20 20 20 72 6f 77 20 63 68 61           row cha
dd00: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
dd10: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
dd20: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a  NSERT, UPDATE,.*
dd30: 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 44 45  *          or DE
dd40: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 6f  LETE statement o
dd50: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
dd60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  ase connection a
dd70: 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  nd.**          w
dd80: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  ithin the same o
dd90: 72 20 68 69 67 68 65 72 20 74 72 69 67 67 65 72  r higher trigger
dda0: 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72   context, or zer
ddb0: 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65 0a  o if there have.
ddc0: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20  **          not 
ddd0: 62 65 65 6e 20 61 6e 79 20 71 75 61 6c 69 66 79  been any qualify
dde0: 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ing row changes.
ddf0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34 33 7d 20  .**.** {F12243} 
de00: 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68  Statements of th
de10: 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46  e form "DELETE F
de20: 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77  ROM tablename" w
de30: 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20  ith no.**       
de40: 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20     WHERE clause 
de50: 73 68 61 6c 6c 20 63 61 75 73 65 20 73 75 62 73  shall cause subs
de60: 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
de70: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
de80: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
de90: 74 6f 20 72 65 74 75 72 6e 20 7a 65 72 6f 2c 20  to return zero, 
dea0: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
deb0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
dec0: 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6f 72 69  mber of rows ori
ded0: 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 20 74  ginally in the t
dee0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  able..**.** LIMI
def0: 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
df00: 55 31 32 32 35 32 7d 20 49 66 20 61 20 73 65 70  U12252} If a sep
df10: 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
df20: 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
df30: 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
df40: 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
df50: 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71         while [sq
df60: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
df70: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
df80: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
df90: 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
dfa0: 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
dfb0: 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
dfc0: 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
dfd0: 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
dfe0: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
dff0: 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
e000: 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
e010: 69 66 69 65 64 20 7b 46 31 32 32 36 30 7d 0a 2a  ified {F12260}.*
e020: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
e030: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
e040: 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
e050: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49  nges caused by I
e060: 4e 53 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54 45  NSERT,.** UPDATE
e070: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
e080: 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20  ments since the 
e090: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
e0a0: 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64  tion] was opened
e0b0: 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69  ..** The count i
e0c0: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e  ncludes all chan
e0d0: 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69  ges from all tri
e0e0: 67 67 65 72 20 63 6f 6e 74 65 78 74 73 2e 20 20  gger contexts.  
e0f0: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20  However,.** the 
e100: 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
e110: 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
e120: 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
e130: 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
e140: 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
e150: 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
e160: 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 44 52  rocessing, or DR
e170: 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73  OP table process
e180: 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e  ing..** The chan
e190: 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20  ges are counted 
e1a0: 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73  as soon as the s
e1b0: 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61  tatement that ma
e1c0: 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63  kes them is.** c
e1d0: 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74  ompleted (when t
e1e0: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
e1f0: 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  dle is passed to
e200: 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
e210: 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
e220: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
e230: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
e240: 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d  lements the comm
e250: 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  and "DELETE FROM
e260: 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20   table" without 
e270: 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a  a WHERE clause.*
e280: 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e  * by dropping an
e290: 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65  d recreating the
e2a0: 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69   table.  (This i
e2b0: 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68  s much faster th
e2c0: 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f  an going.** thro
e2d0: 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67  ugh and deleting
e2e0: 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d   individual elem
e2f0: 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61  ents from the ta
e300: 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f  ble.)  Because o
e310: 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69  f this.** optimi
e320: 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65  zation, the dele
e330: 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45  tions in "DELETE
e340: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65   FROM table" are
e350: 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73   not row changes
e360: 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74   and.** will not
e370: 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74   be counted by t
e380: 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
e390: 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33  es() or [sqlite3
e3a0: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
e3b0: 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20  ].** functions, 
e3c0: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
e3d0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d  e number of elem
e3e0: 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f  ents that were o
e3f0: 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20  riginally.** in 
e400: 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67  the table.  To g
e410: 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63  et an accurate c
e420: 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62  ount of the numb
e430: 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74  er of rows delet
e440: 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45  ed, use.** "DELE
e450: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48  TE FROM table WH
e460: 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a  ERE 1" instead..
e470: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
e480: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
e490: 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
e4a0: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
e4b0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 36  TS:.**.** {F1226
e4c0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
e4d0: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
e4e0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74   returns the tot
e4f0: 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20  al number.**    
e500: 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68 61        of row cha
e510: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49  nges caused by I
e520: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 61  NSERT, UPDATE, a
e530: 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  nd/or DELETE.** 
e540: 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65           stateme
e550: 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  nts on the same 
e560: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
e570: 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a  tion], in any.**
e580: 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65            trigge
e590: 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65  r context, since
e5a0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
e5b0: 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72 65  nnection was cre
e5c0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ated..**.** {F12
e5d0: 32 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20  263} Statements 
e5e0: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c  of the form "DEL
e5f0: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61  ETE FROM tablena
e600: 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20  me" with no.**  
e610: 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c          WHERE cl
e620: 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20 63  ause shall not c
e630: 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
e640: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20  returned.**     
e650: 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33       by [sqlite3
e660: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
e670: 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  ]..**.** LIMITAT
e680: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  IONS:.**.** {U12
e690: 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72 61  264} If a separa
e6a0: 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
e6b0: 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
e6c0: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
e6d0: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
e6e0: 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74      while [sqlit
e6f0: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
e700: 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
e710: 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
e720: 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
e730: 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
e740: 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
e750: 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
e760: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
e770: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
e780: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
e790: 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
e7a0: 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20  g-Running Query 
e7b0: 7b 46 31 32 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12270}.**.** T
e7c0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
e7d0: 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
e7e0: 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
e7f0: 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
e800: 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
e810: 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
e820: 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
e830: 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
e840: 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
e850: 73 70 6f 6e 73 65 20 74 6f 20 61 6e 20 75 73 65  sponse to an use
e860: 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
e870: 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
e880: 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
e890: 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
e8a0: 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
e8b0: 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
e8c0: 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
e8d0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ly..**.** It is 
e8e0: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
e8f0: 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
e900: 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
e910: 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
e920: 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
e930: 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
e940: 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
e950: 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
e960: 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
e970: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
e980: 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
e990: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
e9a0: 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
e9b0: 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
e9c0: 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
e9d0: 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
e9e0: 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  rns..**.** If an
e9f0: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
ea00: 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
ea10: 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
ea20: 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
ea30: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
ea40: 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
ea50: 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
ea60: 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
ea70: 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
ea80: 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
ea90: 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
eaa0: 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  etion..**.** An 
eab0: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
eac0: 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
ead0: 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
eae0: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
eaf0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65  ..** If the inte
eb00: 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
eb10: 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
eb20: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
eb30: 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
eb40: 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
eb50: 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
eb60: 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
eb70: 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
eb80: 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
eb90: 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
eba0: 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  y..**.** A call 
ebb0: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
ebc0: 72 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66  rupt() has no ef
ebd0: 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
ebe0: 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
ebf0: 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
ec00: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
ec10: 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
ec20: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
ec30: 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 31 7d 20 54  **.** {F12271} T
ec40: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  he [sqlite3_inte
ec50: 72 72 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61  rrupt()] interfa
ec60: 63 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c  ce will force al
ec70: 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20  l running.**    
ec80: 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
ec90: 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
eca0: 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 61  with the same da
ecb0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ecc0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  n.**          to
ecd0: 20 68 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63   halt after proc
ece0: 65 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f  essing at most o
ecf0: 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f  ne additional ro
ed00: 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
ed10: 20 7b 46 31 32 32 37 32 7d 20 41 6e 79 20 53 51   {F12272} Any SQ
ed20: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
ed30: 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
ed40: 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  by [sqlite3_inte
ed50: 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20  rrupt()].**     
ed60: 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e       will return
ed70: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
ed80: 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  PT]..**.** LIMIT
ed90: 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55  ATIONS:.**.** {U
eda0: 31 32 32 37 39 7d 20 49 66 20 74 68 65 20 64 61  12279} If the da
edb0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
edc0: 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
edd0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
ede0: 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  t()].**         
edf0: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
ee00: 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
ee10: 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
ee20: 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
ee30: 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
ee40: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
ee50: 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
ee60: 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
ee70: 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20  ent Is Complete 
ee80: 7b 46 31 30 35 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F10510}.**.** T
ee90: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
eea0: 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d  e useful for com
eeb0: 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
eec0: 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
eed0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
eee0: 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
eef0: 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70  ems to form comp
ef00: 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74 65  lete a SQL state
ef10: 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
ef20: 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
ef30: 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
ef40: 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
ef50: 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
ef60: 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68  for parsing.  Th
ef70: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
ef80: 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20  urn true if the 
ef90: 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
efa0: 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
efb0: 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
efc0: 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65  tement.  A state
efd0: 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
efe0: 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
eff0: 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
f000: 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
f010: 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
f020: 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a  fragment of a.**
f030: 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
f040: 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69  statement.  Semi
f050: 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
f060: 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
f070: 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
f080: 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
f090: 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
f0a0: 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
f0b0: 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
f0c0: 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
f0d0: 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
f0e0: 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
f0f0: 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
f100: 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
f110: 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
f120: 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
f130: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
f140: 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
f150: 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
f160: 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
f170: 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
f180: 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
f190: 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
f1a0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
f1b0: 2a 2a 0a 2a 2a 20 7b 46 31 30 35 31 31 7d 20 54  **.** {F10511} T
f1c0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  he sqlite3_compl
f1d0: 65 74 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ete() and sqlite
f1e0: 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 66  3_complete16() f
f1f0: 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 20 20 20 20  unctions.**     
f200: 20 20 20 20 20 72 65 74 75 72 6e 20 74 72 75 65       return true
f210: 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 61   (non-zero) if a
f220: 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 6c  nd only if the l
f230: 61 73 74 20 6e 6f 6e 2d 77 68 69 74 65 73 70 61  ast non-whitespa
f240: 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ce.**          t
f250: 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 20 69 6e  oken in their in
f260: 70 75 74 20 69 73 20 61 20 73 65 6d 69 63 6f 6c  put is a semicol
f270: 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 69  on that is not i
f280: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 20 20 20  n between.**    
f290: 20 20 20 20 20 20 74 68 65 20 42 45 47 49 4e 20        the BEGIN 
f2a0: 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 43 52 45  and END of a CRE
f2b0: 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
f2c0: 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d  ement..**.** LIM
f2d0: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
f2e0: 7b 55 31 30 35 31 32 7d 20 54 68 65 20 69 6e 70  {U10512} The inp
f2f0: 75 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ut to sqlite3_co
f300: 6d 70 6c 65 74 65 28 29 20 6d 75 73 74 20 62 65  mplete() must be
f310: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
f320: 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55  ed.**          U
f330: 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
f340: 2a 2a 20 7b 55 31 30 35 31 33 7d 20 54 68 65 20  ** {U10513} The 
f350: 69 6e 70 75 74 20 74 6f 20 73 71 6c 69 74 65 33  input to sqlite3
f360: 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 6d 75  _complete16() mu
f370: 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
f380: 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  minated.**      
f390: 20 20 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e      UTF-16 strin
f3a0: 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
f3b0: 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73   order..*/.int s
f3c0: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
f3d0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
f3e0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
f3f0: 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
f400: 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
f410: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
f420: 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
f430: 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
f440: 5f 42 55 53 59 20 45 72 72 6f 72 73 20 7b 46 31  _BUSY Errors {F1
f450: 32 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2310}.**.** This
f460: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
f470: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
f480: 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  n that might be 
f490: 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
f4a0: 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
f4b0: 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61  s made to open a
f4c0: 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
f4d0: 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72  that another thr
f4e0: 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
f4f0: 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  s has locked..**
f500: 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20  .** If the busy 
f510: 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
f520: 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
f530: 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
f540: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
f550: 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
f560: 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
f570: 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
f580: 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73  lock. If the bus
f590: 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
f5a0: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
f5b0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c  the callback wil
f5c0: 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  l be invoked wit
f5d0: 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
f5e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
f5f0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
f600: 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
f610: 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
f620: 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
f630: 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
f640: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
f650: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
f660: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
f670: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
f680: 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
f690: 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
f6a0: 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
f6b0: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
f6c0: 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
f6d0: 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b  ed for this lock
f6e0: 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74  ing event.  If t
f6f0: 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
f700: 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
f710: 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
f720: 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
f730: 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
f740: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
f750: 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
f760: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
f770: 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
f780: 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  urned..** If the
f790: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
f7a0: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
f7b0: 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
f7c0: 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  .** is made to o
f7d0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
f7e0: 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
f7f0: 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
f800: 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
f810: 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
f820: 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
f830: 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
f840: 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
f850: 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
f860: 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
f870: 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20  tion. If SQLite 
f880: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
f890: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
f8a0: 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
f8b0: 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
f8c0: 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
f8d0: 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
f8e0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
f8f0: 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  Y].** or [SQLITE
f900: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
f910: 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
f920: 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e  ing the busy han
f930: 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
f940: 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
f950: 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
f960: 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
f970: 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
f980: 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
f990: 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
f9a0: 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
f9b0: 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
f9c0: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
f9d0: 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
f9e0: 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
f9f0: 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
fa00: 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
fa10: 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
fa20: 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
fa30: 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
fa40: 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
fa50: 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
fa60: 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
fa70: 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
fa80: 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
fa90: 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
faa0: 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
fab0: 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
fac0: 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
fad0: 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
fae0: 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
faf0: 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
fb00: 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
fb10: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
fb20: 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
fb30: 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
fb40: 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
fb50: 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
fb60: 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
fb70: 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
fb80: 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
fb90: 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
fba0: 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
fbb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ..**.** The defa
fbc0: 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
fbd0: 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
fbe0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53   The [SQLITE_BUS
fbf0: 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
fc00: 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
fc10: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
fc20: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
fc30: 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
fc40: 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
fc50: 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
fc60: 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
fc70: 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
fc80: 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
fc90: 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
fca0: 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
fcb0: 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
fcc0: 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
fcd0: 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
fce0: 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
fcf0: 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
fd00: 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
fd10: 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
fd20: 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
fd30: 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
fd40: 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
fd50: 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
fd60: 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49  t.** readers.  I
fd70: 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
fd80: 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f  o promote the lo
fd90: 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d  ck, then the in-
fda0: 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20  memory.** cache 
fdb0: 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20  will be left in 
fdc0: 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20  an inconsistent 
fdd0: 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65  state and so the
fde0: 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
fdf0: 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20  s promoted from 
fe00: 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62  the relatively b
fe10: 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55  enign [SQLITE_BU
fe20: 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f  SY] to.** the mo
fe30: 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54  re severe [SQLIT
fe40: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
fe50: 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f  .  This error co
fe60: 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
fe70: 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
fe80: 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
fe90: 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65  the changes.  Se
fea0: 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
feb0: 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  ="/cvstrac/wiki?
fec0: 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
fed0: 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
fee0: 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
fef0: 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
ff00: 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
ff10: 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
ff20: 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
ff30: 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a  s important..**.
ff40: 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c  ** There can onl
ff50: 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
ff60: 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
ff70: 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
ff80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ff90: 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
ffa0: 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
ffb0: 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
ffc0: 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
ffd0: 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68  andler.  Note th
ffe0: 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
fff0: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
10000 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f  ()].** will also
10010 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68   set or clear th
10020 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
10030 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
10040 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 31 7d  :.**.** {F12311}
10050 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75   The [sqlite3_bu
10060 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 66 75  sy_handler()] fu
10070 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
10080 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
10090 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
100a0 6c 62 61 63 6b 20 69 6e 20 74 68 65 20 64 61 74  lback in the dat
100b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
100c0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
100d0 68 65 20 31 73 74 0a 2a 2a 20 20 20 20 20 20 20  he 1st.**       
100e0 20 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74     parameter wit
100f0 68 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  h a new busy han
10100 64 6c 65 72 20 69 64 65 6e 74 69 66 69 65 64 20  dler identified 
10110 62 79 20 74 68 65 20 32 6e 64 20 61 6e 64 20 33  by the 2nd and 3
10120 72 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  rd.**          p
10130 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  arameters..**.**
10140 20 7b 46 31 32 33 31 32 7d 20 54 68 65 20 64 65   {F12312} The de
10150 66 61 75 6c 74 20 62 75 73 79 20 68 61 6e 64 6c  fault busy handl
10160 65 72 20 66 6f 72 20 6e 65 77 20 64 61 74 61 62  er for new datab
10170 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
10180 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  is NULL..**.** {
10190 46 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f  F12314} When two
101a0 20 6f 72 20 6d 6f 72 65 20 64 61 74 61 62 61 73   or more databas
101b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 61  e connection sha
101c0 72 65 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  re a.**         
101d0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
101e0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20  _shared_cache | 
101f0 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a  common cache],.*
10200 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
10210 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
10220 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
10230 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c  nection currentl
10240 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  y using.**      
10250 20 20 20 20 74 68 65 20 63 61 63 68 65 20 69 73      the cache is
10260 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
10270 65 20 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65  e cache encounte
10280 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a  rs a lock..**.**
10290 20 7b 46 31 32 33 31 36 7d 20 49 66 20 61 20 62   {F12316} If a b
102a0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
102b0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72  back returns zer
102c0 6f 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69  o, then the SQLi
102d0 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
102e0 20 20 20 20 20 20 20 20 20 74 68 61 74 20 70 72           that pr
102f0 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69  ovoked the locki
10300 6e 67 20 65 76 65 6e 74 20 77 69 6c 6c 20 72 65  ng event will re
10310 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
10320 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31  Y]..**.** {F1231
10330 38 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  8} SQLite will i
10340 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 73 79 20  nvokes the busy 
10350 68 61 6e 64 6c 65 72 20 77 69 74 68 20 74 77 6f  handler with two
10360 20 61 72 67 75 6d 65 6e 74 73 20 77 68 69 63 68   arguments which
10370 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
10380 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70   a copy of the p
10390 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 65 64 20  ointer supplied 
103a0 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  by the 3rd param
103b0 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eter to.**      
103c0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73      [sqlite3_bus
103d0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61 6e 64  y_handler()] and
103e0 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20   a count of the 
103f0 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 0a  number of prior.
10400 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f  **          invo
10410 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  cations of the b
10420 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
10430 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67  the same locking
10440 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49   event..**.** LI
10450 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
10460 20 7b 55 31 32 33 31 39 7d 20 41 20 62 75 73 79   {U12319} A busy
10470 20 68 61 6e 64 6c 65 72 20 73 68 6f 75 6c 64 20   handler should 
10480 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
10490 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
104a0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
104b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
104c0 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
104d0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
104e0 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
104f0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
10500 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
10510 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
10520 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
10530 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
10540 79 20 54 69 6d 65 6f 75 74 20 7b 46 31 32 33 34  y Timeout {F1234
10550 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0}.**.** This ro
10560 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
10570 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
10580 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
10590 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
105a0 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
105b0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
105c0 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
105d0 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61   locked.  The ha
105e0 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
105f0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
10600 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
10610 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
10620 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
10630 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
10640 74 65 64 2e 20 7b 46 31 32 33 34 33 7d 20 41 66  ted. {F12343} Af
10650 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ter "ms" millise
10660 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
10670 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
10680 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
10690 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
106a0 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
106b0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
106c0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
106d0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a  IOERR_BLOCKED]..
106e0 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68  **.** Calling th
106f0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
10700 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
10710 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
10720 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
10730 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
10740 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dlers..**.** The
10750 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
10760 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
10770 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
10780 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
10790 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
107a0 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  ny any given mom
107b0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
107c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
107d0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
107e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
107f0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
10800 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
10810 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
10820 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
10830 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
10840 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  red..**.** INVAR
10850 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
10860 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2341} The [sqlit
10870 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
10880 29 5d 20 66 75 6e 63 74 69 6f 6e 20 6f 76 65 72  )] function over
10890 72 69 64 65 73 20 61 6e 79 20 70 72 69 6f 72 0a  rides any prior.
108a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
108b0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
108c0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
108d0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
108e0 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
108f0 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65       on the same
10900 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
10910 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  tion..**.** {F12
10920 33 34 33 7d 20 49 66 20 74 68 65 20 32 6e 64 20  343} If the 2nd 
10930 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
10940 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
10950 75 74 28 29 5d 20 69 73 20 6c 65 73 73 20 74 68  ut()] is less th
10960 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  an.**          o
10970 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2c  r equal to zero,
10980 20 74 68 65 6e 20 74 68 65 20 62 75 73 79 20 68   then the busy h
10990 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
109a0 64 20 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20  d so that.**    
109b0 20 20 20 20 20 20 61 6c 6c 20 73 75 62 73 65 71        all subseq
109c0 75 65 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65  uent locking eve
109d0 6e 74 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  nts immediately 
109e0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
109f0 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  USY]..**.** {F12
10a00 33 34 34 7d 20 49 66 20 74 68 65 20 32 6e 64 20  344} If the 2nd 
10a10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
10a20 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
10a30 75 74 28 29 5d 20 69 73 20 61 20 70 6f 73 69 74  ut()] is a posit
10a40 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
10a50 6e 75 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20 61  number N, then a
10a60 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
10a70 20 73 65 74 20 74 68 61 74 20 72 65 70 65 61 74   set that repeat
10a80 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 20 20  edly calls.**   
10a90 20 20 20 20 20 20 20 74 68 65 20 78 53 6c 65 65         the xSlee
10aa0 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20 74 68  p() method in th
10ab0 65 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 20  e VFS interface 
10ac0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
10ad0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 63  .**          loc
10ae0 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e 74 69  k clears or unti
10af0 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69 76 65  l the cumulative
10b00 20 73 6c 65 65 70 20 74 69 6d 65 20 72 65 70 6f   sleep time repo
10b10 72 74 65 64 20 62 61 63 6b 0a 2a 2a 20 20 20 20  rted back.**    
10b20 20 20 20 20 20 20 62 79 20 78 53 6c 65 65 70 28        by xSleep(
10b30 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c  ) exceeds N mill
10b40 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74  iseconds..*/.int
10b50 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
10b60 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
10b70 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
10b80 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
10b90 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
10ba0 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
10bb0 65 73 20 7b 46 31 32 33 37 30 7d 0a 2a 2a 0a 2a  es {F12370}.**.*
10bc0 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
10bd0 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
10be0 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
10bf0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
10c00 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
10c10 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
10c20 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
10c30 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
10c40 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
10c50 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
10c60 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
10c70 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
10c80 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
10c90 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
10ca0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
10cb0 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
10cc0 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
10cd0 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
10ce0 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
10cf0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
10d00 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
10d10 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
10d20 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
10d30 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
10d40 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
10d50 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
10d60 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
10d70 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
10d80 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
10d90 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
10da0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
10db0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
10dc0 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
10dd0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
10de0 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
10df0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
10e00 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
10e10 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
10e20 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
10e30 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
10e40 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
10e50 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
10e60 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
10e70 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
10e80 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
10e90 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
10ea0 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
10eb0 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
10ec0 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
10ed0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
10ee0 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
10ef0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
10f00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
10f10 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
10f20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
10f30 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
10f40 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
10f50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
10f60 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
10f70 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
10f80 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
10f90 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
10fa0 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
10fb0 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
10fc0 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
10fd0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
10fe0 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
10ff0 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65  ** As an example
11000 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
11010 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
11020 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
11030 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
11040 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
11050 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
11060 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
11070 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
11080 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
11090 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
110a0 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
110b0 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
110c0 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
110d0 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
110e0 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
110f0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
11100 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
11110 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
11120 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
11130 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
11140 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
11150 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
11160 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
11170 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
11180 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
11190 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
111a0 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
111b0 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
111c0 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
111d0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
111e0 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
111f0 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
11200 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
11210 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
11220 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
11230 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
11240 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
11250 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
11260 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
11270 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
11280 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
11290 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
112a0 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
112b0 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
112c0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
112d0 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
112e0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
112f0 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
11300 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
11310 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ote>.**.** The s
11320 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
11330 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
11340 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
11350 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
11360 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
11370 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
11380 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
11390 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
113a0 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
113b0 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ter.  It returns
113c0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
113d0 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
113e0 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
113f0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
11400 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63 61  .** After the ca
11410 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68  lling function h
11420 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
11430 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74  g the result, it
11440 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20   should.** pass 
11450 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
11460 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
11470 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
11480 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
11490 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
114a0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
114b0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
114c0 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
114d0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
114e0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
114f0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
11500 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
11510 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
11520 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
11530 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
11540 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
11550 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
11560 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
11570 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
11580 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
11590 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
115a0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
115b0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
115c0 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
115d0 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
115e0 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
115f0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
11600 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
11610 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
11620 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
11630 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
11640 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
11650 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
11660 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
11670 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
11680 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
11690 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
116a0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
116b0 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
116c0 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
116d0 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
116e0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
116f0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
11700 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
11710 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
11720 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
11730 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
11740 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 20  3_errcode()] or 
11750 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
11760 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
11770 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
11780 33 37 31 7d 20 49 66 20 61 20 5b 73 71 6c 69 74  371} If a [sqlit
11790 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
117a0 66 61 69 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61  fails a memory a
117b0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a  llocation, then.
117c0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74 20 66  **          it f
117d0 72 65 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  rees the result 
117e0 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73  table under cons
117f0 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74 73  truction, aborts
11800 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
11810 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65 73   query in proces
11820 73 2c 20 73 6b 69 70 73 20 61 6e 79 20 73 75 62  s, skips any sub
11830 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c  sequent queries,
11840 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 20 20 20   sets the.**    
11850 20 20 20 20 20 20 2a 72 65 73 75 6c 74 70 20 6f        *resultp o
11860 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74 6f  utput pointer to
11870 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e   NULL and return
11880 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  s [SQLITE_NOMEM]
11890 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 33 7d  ..**.** {F12373}
118a0 20 49 66 20 74 68 65 20 6e 63 6f 6c 75 6d 6e 20   If the ncolumn 
118b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
118c0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
118d0 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a  )] is not NULL.*
118e0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
118f0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
11900 6c 65 28 29 5d 20 77 72 69 74 65 73 20 74 68 65  le()] writes the
11910 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
11920 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ns in the.**    
11930 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74        result set
11940 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e   of the query in
11950 74 6f 20 2a 6e 63 6f 6c 75 6d 6e 20 69 66 20 74  to *ncolumn if t
11960 68 65 20 71 75 65 72 79 20 69 73 0a 2a 2a 20 20  he query is.**  
11970 20 20 20 20 20 20 20 20 73 75 63 63 65 73 73 66          successf
11980 75 6c 20 28 69 66 20 74 68 65 20 66 75 6e 63 74  ul (if the funct
11990 69 6f 6e 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ion returns SQLI
119a0 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46  TE_OK)..**.** {F
119b0 31 32 33 37 34 7d 20 49 66 20 74 68 65 20 6e 72  12374} If the nr
119c0 6f 77 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ow parameter to 
119d0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
119e0 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c  le()] is not NUL
119f0 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  L.**          th
11a00 65 6e 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  en [sqlite3_get_
11a10 74 61 62 6c 65 28 29 5d 20 77 72 69 74 65 73 20  table()] writes 
11a20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
11a30 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ws in the.**    
11a40 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74        result set
11a50 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e   of the query in
11a60 74 6f 20 2a 6e 72 6f 77 20 69 66 20 74 68 65 20  to *nrow if the 
11a70 71 75 65 72 79 20 69 73 0a 2a 2a 20 20 20 20 20  query is.**     
11a80 20 20 20 20 20 73 75 63 63 65 73 73 66 75 6c 20       successful 
11a90 28 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  (if the function
11aa0 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
11ab0 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  OK)..**.** {F123
11ac0 37 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  76} The [sqlite3
11ad0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 75  _get_table()] fu
11ae0 6e 63 74 69 6f 6e 20 73 65 74 73 20 69 74 73 20  nction sets its 
11af0 2a 6e 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 20 74  *ncolumn value t
11b00 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
11b10 20 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75    number of colu
11b20 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
11b30 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65  t set of the que
11b40 72 79 20 69 6e 20 74 68 65 20 73 71 6c 0a 2a 2a  ry in the sql.**
11b50 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
11b60 74 65 72 2c 20 6f 72 20 74 6f 20 7a 65 72 6f 20  ter, or to zero 
11b70 69 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 20  if the query in 
11b80 73 71 6c 20 68 61 73 20 61 6e 20 65 6d 70 74 79  sql has an empty
11b90 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a   result set..*/.
11ba0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
11bb0 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
11bc0 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  *,             /
11bd0 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
11be0 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
11bf0 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 2f 2a  ar *sql,      /*
11c00 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
11c10 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
11c20 2a 2a 70 52 65 73 75 6c 74 2c 20 20 20 20 20 20  **pResult,      
11c30 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
11c40 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
11c50 20 2a 6e 72 6f 77 2c 20 20 20 20 20 20 20 20 20   *nrow,         
11c60 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
11c70 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
11c80 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
11c90 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20 20  t *ncolumn,     
11ca0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
11cb0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
11cc0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
11cd0 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
11ce0 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
11cf0 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
11d00 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
11d10 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
11d20 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
11d30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11d40 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
11d50 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
11d60 69 6f 6e 73 20 7b 46 31 37 34 30 30 7d 0a 2a 2a  ions {F17400}.**
11d70 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
11d80 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65  es are workalike
11d90 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
11da0 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
11db0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
11dc0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
11dd0 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  ibrary..**.** Th
11de0 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
11df0 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
11e00 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
11e10 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
11e20 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
11e30 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
11e40 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
11e50 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
11e60 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
11e70 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
11e80 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
11e90 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
11ea0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
11eb0 2e 20 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65  .   Both routine
11ec0 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
11ed0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
11ee0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
11ef0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
11f00 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
11f10 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
11f20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
11f30 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73  ring..**.** In s
11f40 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
11f50 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
11f60 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
11f70 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
11f80 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
11f90 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
11fa0 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
11fb0 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
11fc0 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
11fd0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
11fe0 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
11ff0 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
12000 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
12010 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
12020 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
12030 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
12040 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
12050 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20  om snprintf().  
12060 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
12070 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
12080 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
12090 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
120a0 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
120b0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
120c0 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74  ty.  Note also t
120d0 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
120e0 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
120f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
12100 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
12110 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
12120 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
12130 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
12140 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
12150 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  r.  We admit tha
12160 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
12170 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
12180 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
12190 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
121a0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
121b0 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
121c0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
121d0 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
121e0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
121f0 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
12200 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
12210 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20  ..**.** As long 
12220 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
12230 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
12240 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
12250 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
12260 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
12270 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
12280 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
12290 74 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a  ted.  The first.
122a0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
122b0 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
122c0 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
122d0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
122e0 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
122f0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
12300 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
12310 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
12320 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
12330 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
12340 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
12350 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
12360 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e  nes all implemen
12370 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  t some additiona
12380 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20  l formatting.** 
12390 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  options that are
123a0 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73   useful for cons
123b0 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61  tructing SQL sta
123c0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20  tements..** All 
123d0 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69  of the usual pri
123e0 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67  ntf() formatting
123f0 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20   options apply. 
12400 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68   In addition, th
12410 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25  ere.** is are "%
12420 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25  q", "%Q", and "%
12430 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  z" options..**.*
12440 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  * The %q option 
12450 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
12460 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
12470 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d  utes a null-term
12480 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
12490 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
124a0 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
124b0 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
124c0 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
124d0 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
124e0 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
124f0 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
12500 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c  teral.  By doubl
12510 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
12520 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
12530 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
12540 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
12550 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
12560 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
12570 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
12580 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
12590 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
125a0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
125b0 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
125c0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
125d0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
125e0 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
125f0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
12600 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
12610 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
12620 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
12630 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
12640 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
12650 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
12660 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
12670 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
12680 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
12690 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
126a0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
126b0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
126c0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
126d0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
126e0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
126f0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
12700 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
12710 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
12720 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
12730 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
12740 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
12750 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
12760 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
12770 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
12780 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
12790 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
127a0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
127b0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
127c0 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
127d0 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
127e0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
127f0 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
12800 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
12810 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
12820 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
12830 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
12840 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
12850 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
12860 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
12870 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
12880 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
12890 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
128a0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
128b0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
128c0 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
128d0 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
128e0 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
128f0 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
12900 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
12910 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
12920 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
12930 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
12940 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
12950 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74  **.** The %Q opt
12960 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
12970 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
12980 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
12990 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
129a0 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
129b0 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
129c0 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
129d0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
129e0 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
129f0 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
12a00 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
12a10 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
12a20 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
12a30 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
12a40 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  es) in place of 
12a50 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 7b  the %Q option. {
12a60 45 4e 44 7d 20 20 53 6f 2c 20 66 6f 72 20 65 78  END}  So, for ex
12a70 61 6d 70 6c 65 2c 0a 2a 2a 20 6f 6e 65 20 63 6f  ample,.** one co
12a80 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
12a90 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12aa0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
12ab0 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
12ac0 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
12ad0 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
12ae0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
12af0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
12b00 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
12b10 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
12b20 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
12b30 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
12b40 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
12b50 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
12b60 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
12b70 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
12b80 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
12b90 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
12ba0 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
12bb0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
12bc0 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d  ** The "%z" form
12bd0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
12be0 72 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65  rks exactly like
12bf0 20 22 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a   "%s" with the.*
12c00 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
12c10 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
12c20 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
12c30 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
12c40 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
12c50 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
12c60 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
12c70 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45  input string. {E
12c80 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ND}.**.** INVARI
12c90 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ANTS:.**.** {F17
12ca0 34 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  403}  The [sqlit
12cb0 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e  e3_mprintf()] an
12cc0 64 20 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  d [sqlite3_vmpri
12cd0 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ntf()] interface
12ce0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  s.**           r
12cf0 65 74 75 72 6e 20 65 69 74 68 65 72 20 70 6f 69  eturn either poi
12d00 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
12d10 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
12d20 74 72 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a  trings held in.*
12d30 2a 20 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f  *           memo
12d40 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
12d50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
12d60 28 29 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e  ()] or NULL poin
12d70 74 65 72 73 20 69 66 0a 2a 2a 20 20 20 20 20 20  ters if.**      
12d80 20 20 20 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b       a call to [
12d90 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
12da0 5d 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b  ] fails..**.** {
12db0 46 31 37 34 30 36 7d 20 20 54 68 65 20 5b 73 71  F17406}  The [sq
12dc0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
12dd0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74  ] interface writ
12de0 65 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  es a zero-termin
12df0 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
12e00 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69    UTF-8 string i
12e10 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 20 70  nto the buffer p
12e20 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
12e30 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
12e40 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 70  r.**           p
12e50 72 6f 76 69 64 65 64 20 74 68 61 74 20 74 68 65  rovided that the
12e60 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
12e70 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
12e80 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   zero..**.** {F1
12e90 37 34 30 37 7d 20 20 54 68 65 20 5b 73 71 6c 69  7407}  The [sqli
12ea0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
12eb0 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
12ec0 6f 74 20 77 72 69 74 65 20 73 6c 6f 74 73 20 6f  ot write slots o
12ed0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69  f.**           i
12ee0 74 73 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ts output buffer
12ef0 20 28 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72   (the second par
12f00 61 6d 65 74 65 72 29 20 6f 75 74 73 69 64 65 20  ameter) outside 
12f10 74 68 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20  the range.**    
12f20 20 20 20 20 20 20 20 6f 66 20 30 20 74 68 72 6f         of 0 thro
12f30 75 67 68 20 4e 2d 31 20 28 77 68 65 72 65 20 4e  ugh N-1 (where N
12f40 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
12f50 72 61 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20 20  rameter).**     
12f60 20 20 20 20 20 20 72 65 67 61 72 64 6c 65 73 73        regardless
12f70 20 6f 66 20 74 68 65 20 6c 65 6e 67 74 68 20 6f   of the length o
12f80 66 20 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20  f the string.** 
12f90 20 20 20 20 20 20 20 20 20 20 72 65 71 75 65 73            reques
12fa0 74 65 64 20 62 79 20 74 68 65 20 66 6f 72 6d 61  ted by the forma
12fb0 74 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e  t specification.
12fc0 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
12fd0 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
12fe0 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
12ff0 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
13000 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
13010 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
13020 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
13030 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
13040 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f   char*, ...);../
13050 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
13060 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
13070 20 53 75 62 73 79 73 74 65 6d 20 7b 46 31 37 33   Subsystem {F173
13080 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  00}.**.** The SQ
13090 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65 73 20  Lite core  uses 
130a0 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
130b0 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
130c0 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
130d0 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
130e0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
130f0 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
13100 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
13110 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
13120 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
13130 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
13140 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
13150 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
13160 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
13170 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
13180 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
13190 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ations..**.** Th
131a0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
131b0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
131c0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
131d0 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
131e0 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
131f0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
13200 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
13210 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66  parameter..** If
13220 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
13230 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
13240 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
13250 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
13260 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
13270 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
13280 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
13290 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
132a0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
132b0 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
132c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
132d0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
132e0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
132f0 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  * Calling sqlite
13300 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
13310 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
13320 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
13330 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
13340 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
13350 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
13360 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
13370 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
13380 20 62 65 20 72 65 75 73 65 64 2e 20 20 54 68 65   be reused.  The
13390 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
133a0 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
133b0 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
133c0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
133d0 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
133e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
133f0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
13400 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
13410 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
13420 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
13430 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
13440 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
13450 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
13460 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
13470 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
13480 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
13490 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
134a0 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
134b0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
134c0 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
134d0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
134e0 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
134f0 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
13500 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
13510 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
13520 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
13530 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
13540 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
13550 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
13560 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
13570 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 2e   sqlite3_free().
13580 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
13590 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
135a0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
135b0 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
135c0 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
135d0 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
135e0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
135f0 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
13600 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
13610 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
13620 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
13630 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
13640 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
13650 72 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74  r.  If the first
13660 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
13670 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
13680 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
13690 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
136a0 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
136b0 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
136c0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
136d0 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74  (N) where N is t
136e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
136f0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
13700 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20  ealloc()..** If 
13710 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
13720 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
13730 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  realloc() is zer
13740 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65  o or.** negative
13750 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
13760 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68  or is exactly th
13770 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e  e same as callin
13780 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65  g.** sqlite3_fre
13790 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20  e(P) where P is 
137a0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
137b0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
137c0 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c  ealloc()..** sql
137d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
137e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
137f0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
13800 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
13810 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
13820 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
13830 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
13840 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
13850 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74  le..** If M is t
13860 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
13870 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
13880 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
13890 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
138a0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
138b0 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
138c0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
138d0 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
138e0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
138f0 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65  ealloc() and the
13900 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
13910 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49  n is freed..** I
13920 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
13930 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  c() returns NULL
13940 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72  , then the prior
13950 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
13960 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
13970 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  ** The memory re
13980 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
13990 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73  3_malloc() and s
139a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
139b0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
139c0 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
139d0 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
139e0 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  dary. {END}.**.*
139f0 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d  * The default im
13a00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
13a10 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
13a20 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
13a30 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c  uses.** the mall
13a40 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
13a50 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76 69  and free() provi
13a60 64 65 64 20 62 79 20 74 68 65 20 73 74 61 6e 64  ded by the stand
13a70 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
13a80 2a 20 7b 46 31 37 33 38 32 7d 20 48 6f 77 65 76  * {F17382} Howev
13a90 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73  er, if SQLite is
13aa0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
13ab0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d  he.** SQLITE_MEM
13ac0 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c  ORY_SIZE=<i>NNN<
13ad0 2f 69 3e 20 43 20 70 72 65 70 72 6f 63 65 73 73  /i> C preprocess
13ae0 6f 72 20 6d 61 63 72 6f 20 28 77 68 65 72 65 20  or macro (where 
13af0 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73  <i>NNN</i>.** is
13b00 20 61 6e 20 69 6e 74 65 67 65 72 29 2c 20 74 68   an integer), th
13b10 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74 65  en SQLite create
13b20 20 61 20 73 74 61 74 69 63 20 61 72 72 61 79 20   a static array 
13b30 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c  of at least.** <
13b40 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20  i>NNN</i> bytes 
13b50 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65 73  in size and uses
13b60 20 74 68 61 74 20 61 72 72 61 79 20 66 6f 72 20   that array for 
13b70 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
13b80 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ic.** memory all
13b90 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b  ocation needs. {
13ba0 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c  END}  Additional
13bb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13bc0 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79  r options.** may
13bd0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
13be0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
13bf0 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
13c00 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
13c10 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
13c20 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
13c30 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
13c40 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
13c50 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
13c60 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
13c70 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
13c80 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
13c90 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
13ca0 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
13cb0 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
13cc0 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
13cd0 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
13ce0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
13cf0 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
13d00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f  .**.** The Windo
13d10 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
13d20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74  layer calls.** t
13d30 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
13d40 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
13d50 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
13d60 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
13d70 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
13d80 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
13d90 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
13da0 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
13db0 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
13dc0 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
13dd0 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
13de0 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
13df0 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
13e00 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65  ation errors are
13e10 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
13e20 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72  * they are repor
13e30 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
13e40 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
13e50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
13e60 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
13e70 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
13e80 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
13e90 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 33 7d 20  .**.** {F17303} 
13ea0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   The [sqlite3_ma
13eb0 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61  lloc(N)] interfa
13ec0 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
13ed0 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  r a pointer to.*
13ee0 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 6e 65  *           a ne
13ef0 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75 74 20  wly checked-out 
13f00 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65 61 73  block of at leas
13f10 74 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  t N bytes of mem
13f20 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ory.**          
13f30 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65 20   that is 8-byte 
13f40 61 6c 69 67 6e 65 64 2c 20 6f 72 20 69 74 20 72  aligned, or it r
13f50 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69  eturns NULL if i
13f60 74 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 20  t is unable.**  
13f70 20 20 20 20 20 20 20 20 20 74 6f 20 66 75 6c 66           to fulf
13f80 69 6c 6c 20 74 68 65 20 72 65 71 75 65 73 74 2e  ill the request.
13f90 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 34 7d 20  .**.** {F17304} 
13fa0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   The [sqlite3_ma
13fb0 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61  lloc(N)] interfa
13fc0 63 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ce returns a NUL
13fd0 4c 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a 20  L pointer if.** 
13fe0 20 20 20 20 20 20 20 20 20 20 4e 20 69 73 20 6c            N is l
13ff0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
14000 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  l to zero..**.**
14010 20 7b 46 31 37 33 30 35 7d 20 20 54 68 65 20 5b   {F17305}  The [
14020 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d  sqlite3_free(P)]
14030 20 69 6e 74 65 72 66 61 63 65 20 72 65 6c 65 61   interface relea
14040 73 65 73 20 6d 65 6d 6f 72 79 20 70 72 65 76 69  ses memory previ
14050 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ously.**        
14060 20 20 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d     returned from
14070 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14080 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
14090 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20  realloc()],.**  
140a0 20 20 20 20 20 20 20 20 20 6d 61 6b 69 6e 67 20           making 
140b0 69 74 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72  it available for
140c0 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46   reuse..**.** {F
140d0 31 37 33 30 36 7d 20 20 41 20 63 61 6c 6c 20 74  17306}  A call t
140e0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
140f0 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68 61 72 6d  NULL)] is a harm
14100 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
14110 2a 20 7b 46 31 37 33 31 30 7d 20 20 41 20 63 61  * {F17310}  A ca
14120 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
14130 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73 20  ealloc(0,N)] is 
14140 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20  equivalent to a 
14150 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  call.**         
14160 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61    to [sqlite3_ma
14170 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20  lloc(N)]..**.** 
14180 7b 46 31 37 33 31 32 7d 20 20 41 20 63 61 6c 6c  {F17312}  A call
14190 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   to [sqlite3_rea
141a0 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20 65 71  lloc(P,0)] is eq
141b0 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61  uivalent to a ca
141c0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ll.**           
141d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
141e0 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  (P)]..**.** {F17
141f0 33 31 35 7d 20 20 54 68 65 20 53 51 4c 69 74 65  315}  The SQLite
14200 20 63 6f 72 65 20 75 73 65 73 20 5b 73 71 6c 69   core uses [sqli
14210 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
14220 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
14230 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
14240 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 72   and [sqlite3_fr
14250 65 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f 66  ee()] for all of
14260 20 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   its memory allo
14270 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20  cation and.**   
14280 20 20 20 20 20 20 20 20 64 65 61 6c 6c 6f 63 61          dealloca
14290 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  tion needs..**.*
142a0 2a 20 7b 46 31 37 33 31 38 7d 20 20 54 68 65 20  * {F17318}  The 
142b0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
142c0 28 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (P,N)] interface
142d0 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 20   returns either 
142e0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20  a pointer.**    
142f0 20 20 20 20 20 20 20 74 6f 20 61 20 62 6c 6f 63         to a bloc
14300 6b 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75 74  k of checked-out
14310 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65   memory of at le
14320 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
14330 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ize.**          
14340 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65 20   that is 8-byte 
14350 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e 55  aligned, or a NU
14360 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
14370 2a 20 7b 46 31 37 33 32 31 7d 20 20 57 68 65 6e  * {F17321}  When
14380 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
14390 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20  c(P,N)] returns 
143a0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
143b0 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20  er, it first.** 
143c0 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 73            copies
143d0 20 74 68 65 20 66 69 72 73 74 20 4b 20 62 79 74   the first K byt
143e0 65 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66 72  es of content fr
143f0 6f 6d 20 50 20 69 6e 74 6f 20 74 68 65 20 6e 65  om P into the ne
14400 77 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  wly.**          
14410 20 61 6c 6c 6f 63 61 74 65 64 20 62 6c 6f 63 6b   allocated block
14420 2c 20 77 68 65 72 65 20 4b 20 69 73 20 74 68 65  , where K is the
14430 20 6c 65 73 73 65 72 20 6f 66 20 4e 20 61 6e 64   lesser of N and
14440 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
14450 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62 75            the bu
14460 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ffer P..**.** {F
14470 31 37 33 32 32 7d 20 20 57 68 65 6e 20 5b 73 71  17322}  When [sq
14480 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
14490 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  N)] returns a no
144a0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
144b0 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  it first.**     
144c0 20 20 20 20 20 20 72 65 6c 65 61 73 65 73 20 74        releases t
144d0 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  he buffer P..**.
144e0 2a 2a 20 7b 46 31 37 33 32 33 7d 20 20 57 68 65  ** {F17323}  Whe
144f0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  n [sqlite3_reall
14500 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73  oc(P,N)] returns
14510 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66 66 65   NULL, the buffe
14520 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  r P is.**       
14530 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64      not modified
14540 20 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a   or released..**
14550 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
14560 0a 2a 2a 0a 2a 2a 20 7b 55 31 37 33 35 30 7d 20  .**.** {U17350} 
14570 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
14580 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
14590 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
145a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
145b0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
145c0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
145d0 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
145e0 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
145f0 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 20 20  om a prior.**   
14600 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69          invocati
14610 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
14620 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
14630 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
14640 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 20 20 20  that have.**    
14650 20 20 20 20 20 20 20 6e 6f 74 20 79 65 74 20 62         not yet b
14660 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
14670 0a 2a 2a 20 7b 55 31 37 33 35 31 7d 20 20 54 68  .** {U17351}  Th
14680 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
14690 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
146a0 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
146b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20  .**           a 
146c0 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
146d0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
146e0 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
146f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
14700 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
14710 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
14720 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
14730 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
14740 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
14750 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
14760 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
14770 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
14780 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14790 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
147a0 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 20 7b  tor Statistics {
147b0 46 31 37 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 53 51  F17370}.**.** SQ
147c0 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
147d0 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
147e0 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
147f0 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
14800 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
14810 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
14820 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
14830 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
14840 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
14850 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
14860 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
14870 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
14880 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49  bsystem..**.** I
14890 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
148a0 20 7b 46 31 37 33 37 31 7d 20 54 68 65 20 5b 73   {F17371} The [s
148b0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
148c0 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
148d0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
148e0 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 20 20 20   of bytes.**    
148f0 20 20 20 20 20 20 6f 66 20 6d 65 6d 6f 72 79 20        of memory 
14900 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
14910 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
14920 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
14930 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 33 7d 20 54  **.** {F17373} T
14940 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
14950 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
14960 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
14970 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20  the maximum.**  
14980 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
14990 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
149a0 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
149b0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
149c0 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  rk.**          w
149d0 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a  as last reset..*
149e0 2a 0a 2a 2a 20 7b 46 31 37 33 37 34 7d 20 54 68  *.** {F17374} Th
149f0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
14a00 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
14a10 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
14a20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
14a30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
14a40 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
14a50 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
14a60 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 65 64  *          added
14a70 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
14a80 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
14a90 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
14aa0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  loc()],.**      
14ab0 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65 72      but not over
14ac0 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
14ad0 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
14ae0 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
14af0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74  **          rout
14b00 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
14b10 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
14b20 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   call..**.** {F1
14b30 37 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72 79  7375} The memory
14b40 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
14b50 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
14b60 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
14b70 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  f.**          [s
14b80 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
14b90 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
14ba0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
14bb0 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
14bc0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72    [sqlite3_memor
14bd0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
14be0 73 20 74 72 75 65 2e 20 20 54 68 65 20 76 61 6c  s true.  The val
14bf0 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20  ue returned.**  
14c00 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69          by [sqli
14c10 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
14c20 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
14c30 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
14c40 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 6f  **          prio
14c50 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
14c60 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
14c70 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
14c80 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
14c90 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
14ca0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
14cb0 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
14cc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
14cd0 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
14ce0 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
14cf0 6f 72 20 7b 46 31 37 33 39 30 7d 0a 2a 2a 0a 2a  or {F17390}.**.*
14d00 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
14d10 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
14d20 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
14d30 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
14d40 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
14d50 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
14d60 52 4f 57 49 44 73 20 77 68 65 6e 20 69 6e 73 65  ROWIDs when inse
14d70 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
14d80 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
14d90 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
14da0 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
14db0 70 6f 73 73 69 62 6c 65 20 52 4f 57 49 44 2e 20  possible ROWID. 
14dc0 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73   The PRNG is als
14dd0 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68  o used for.** th
14de0 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f  e build-in rando
14df0 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c  m() and randombl
14e00 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  ob() SQL functio
14e10 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66  ns.  This interf
14e20 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70  ace allows.** ap
14e30 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63  plications to ac
14e40 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52  cess the same PR
14e50 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72  NG for other pur
14e60 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  poses..**.** A c
14e70 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
14e80 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
14e90 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
14ea0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
14eb0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
14ec0 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e  time this routin
14ed0 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69  e is invoked (ei
14ee0 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
14ef0 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70  or by.** the app
14f00 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52  lication) the PR
14f10 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69  NG is seeded usi
14f20 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
14f30 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74  tained.** from t
14f40 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
14f50 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
14f60 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
14f70 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e  s] object..** On
14f80 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
14f90 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65  invocations, the
14fa0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
14fb0 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
14fc0 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
14fd0 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
14fe0 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
14ff0 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
15000 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
15010 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
15020 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 39 32 7d 20  .**.** {F17392} 
15030 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e  The [sqlite3_ran
15040 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e  domness(N,P)] in
15050 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20 4e  terface writes N
15060 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20   bytes of.**    
15070 20 20 20 20 20 20 68 69 67 68 2d 71 75 61 6c 69        high-quali
15080 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
15090 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
150a0 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69   P..*/.void sqli
150b0 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
150c0 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
150d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
150e0 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
150f0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
15100 62 61 63 6b 73 20 7b 46 31 32 35 30 30 7d 0a 2a  backs {F12500}.*
15110 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
15120 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75  e registers a au
15130 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15140 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
15150 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
15160 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
15170 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
15180 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
15190 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
151a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
151b0 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
151c0 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
151d0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
151e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
151f0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
15200 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
15210 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
15220 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
15230 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
15240 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
15250 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a  .  At various.**
15260 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
15270 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
15280 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
15290 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
152a0 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
152b0 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
152c0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
152d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
152e0 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
152f0 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
15300 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65  re allowed.  The
15310 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
15320 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
15330 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
15340 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
15350 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
15360 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
15370 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
15380 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
15390 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
153a0 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
153b0 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
153c0 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
153d0 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
153e0 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
153f0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
15400 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
15410 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 74 68 65  n error.  If the
15420 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
15430 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
15440 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
15450 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
15460 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
15470 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
15480 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
15490 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
154a0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
154b0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
154c0 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
154d0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
154e0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
154f0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
15500 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
15510 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
15520 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
15530 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
15540 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
15550 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20  s ok.  When the 
15560 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
15570 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
15580 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
15590 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
155a0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
155b0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
155c0 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
155d0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
155e0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
155f0 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
15600 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
15610 65 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20 61  enied.  If the a
15620 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 69  uthorizer code i
15630 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
15640 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
15650 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
15660 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
15670 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
15680 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
15690 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
156a0 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
156b0 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
156c0 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
156d0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
156e0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
156f0 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
15700 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
15710 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
15720 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
15730 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
15740 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
15750 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
15760 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
15770 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
15780 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
15790 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
157a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
157b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
157c0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
157d0 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
157e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
157f0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
15800 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
15810 61 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  ace. The second 
15820 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
15830 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
15840 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
15850 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
15860 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
15870 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
15880 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
15890 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
158a0 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75   The third throu
158b0 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
158c0 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
158d0 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d  llback are zero-
158e0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
158f0 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
15900 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65  additional.** de
15910 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
15920 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
15930 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41  horized..**.** A
15940 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
15950 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
15960 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
15970 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
15980 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
15990 6e 20 75 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73  n untrusted.** s
159a0 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
159b0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
159c0 61 74 65 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20  atements do not 
159d0 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
159e0 74 61 0a 2a 2a 20 74 68 61 74 20 74 68 65 79 20  ta.** that they 
159f0 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
15a00 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
15a10 74 68 65 79 20 64 6f 20 6e 6f 74 20 74 72 79 20  they do not try 
15a20 74 6f 0a 2a 2a 20 65 78 65 63 75 74 65 20 6d 61  to.** execute ma
15a30 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
15a40 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
15a50 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
15a60 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
15a70 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
15a80 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
15a90 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
15aa0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
15ab0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
15ac0 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
15ad0 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
15ae0 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
15af0 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
15b00 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
15b10 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
15b20 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
15b30 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
15b40 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
15b50 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
15b60 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
15b70 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
15b80 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
15b90 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
15ba0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
15bb0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
15bc0 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
15bd0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
15be0 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
15bf0 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
15c00 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
15c10 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
15c20 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
15c30 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
15c40 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
15c50 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
15c60 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
15c70 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
15c80 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
15c90 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
15ca0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
15cb0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
15cc0 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
15cd0 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69  .**.** Only a si
15ce0 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
15cf0 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
15d00 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
15d10 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
15d20 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
15d30 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
15d40 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
15d50 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
15d60 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73  vious call.  Dis
15d70 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
15d80 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
15d90 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
15da0 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
15db0 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
15dc0 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
15dd0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
15de0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
15df0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
15e00 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b  only during.** [
15e10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
15e20 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
15e30 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
15e40 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
15e50 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
15e60 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
15e70 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
15e80 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  tep()]..**.** IN
15e90 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
15ea0 7b 46 31 32 35 30 31 7d 20 54 68 65 20 5b 73 71  {F12501} The [sq
15eb0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
15ec0 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74  izer(D,...)] int
15ed0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
15ee0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61   a.**          a
15ef0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
15f00 63 6b 20 77 69 74 68 20 64 61 74 61 62 61 73 65  ck with database
15f10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
15f20 2a 0a 2a 2a 20 7b 46 31 32 35 30 32 7d 20 54 68  *.** {F12502} Th
15f30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
15f40 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
15f50 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
15f60 74 73 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20  ts are.**       
15f70 20 20 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65     being compile
15f80 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 33  d..**.** {F12503
15f90 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69  } If the authori
15fa0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
15fb0 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 65 20 6f  urns any value o
15fc0 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
15fd0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47        [SQLITE_IG
15fe0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
15ff0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
16000 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  ENY], then.**   
16010 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
16020 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
16030 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
16040 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64  call that caused
16050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
16060 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16070 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c  back to run shal
16080 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 0a 2a  l fail with an.*
16090 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
160a0 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20  TE_ERROR] error 
160b0 63 6f 64 65 20 61 6e 64 20 61 6e 20 61 70 70 72  code and an appr
160c0 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65  opriate error me
160d0 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ssage..**.** {F1
160e0 32 35 30 34 7d 20 57 68 65 6e 20 74 68 65 20 61  2504} When the a
160f0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16100 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
16110 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65 72  TE_OK], the oper
16120 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ation.**        
16130 20 20 64 65 73 63 72 69 62 65 64 20 69 73 20 70    described is p
16140 72 6f 63 65 73 73 65 64 20 6e 6f 72 6d 61 6c 6c  rocessed normall
16150 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 35  y..**.** {F12505
16160 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f  } When the autho
16170 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
16180 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
16190 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 20 20  ENY], the.**    
161a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
161b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
161c0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
161d0 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 0a  that caused the.
161e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68  **          auth
161f0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
16200 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69  to run shall fai
16210 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  l.**          wi
16220 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45 52  th an [SQLITE_ER
16230 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20  ROR] error code 
16240 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  and an error mes
16250 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  sage.**         
16260 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
16270 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
16280 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 36  d..**.** {F12506
16290 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69  } If the authori
162a0 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e  zer code (the 2n
162b0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
162c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a  he authorizer.**
162d0 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
162e0 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ck) is [SQLITE_R
162f0 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61 75 74  EAD] and the aut
16300 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
16310 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
16320 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e       [SQLITE_IGN
16330 4f 52 45 5d 2c 20 74 68 65 6e 20 74 68 65 20 70  ORE], then the p
16340 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
16350 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
16360 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
16370 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61  insert a NULL va
16380 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
16390 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
163a0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
163b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 65  .**          bee
163c0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
163d0 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
163e0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eturned..**.** {
163f0 46 31 32 35 30 37 7d 20 49 66 20 74 68 65 20 61  F12507} If the a
16400 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28  uthorizer code (
16410 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
16420 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
16430 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  zer.**          
16440 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e 79  callback) is any
16450 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
16460 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c 20   [SQLITE_READ], 
16470 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
16480 20 61 20 72 65 74 75 72 6e 20 6f 66 20 5b 53 51   a return of [SQ
16490 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61 73  LITE_IGNORE] has
164a0 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63 74   the same effect
164b0 20 61 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   as [SQLITE_DENY
164c0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 30  ]..**.** {F12510
164d0 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
164e0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
164f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
16500 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
16510 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74 68            the th
16520 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
16530 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
16540 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
16550 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
16560 20 7b 46 31 32 35 31 31 7d 20 54 68 65 20 73 65   {F12511} The se
16570 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
16580 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
16590 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
165a0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
165b0 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
165c0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
165d0 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75 6c  ies the particul
165e0 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  ar action.**    
165f0 20 20 20 20 20 20 74 6f 20 62 65 20 61 75 74 68        to be auth
16600 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  orized..**.** {F
16610 31 32 35 31 32 7d 20 54 68 65 20 74 68 69 72 64  12512} The third
16620 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
16630 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
16640 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a 2a   callback are.**
16650 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
16660 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
16670 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 0a 2a  s that contain.*
16680 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 69 74  *          addit
16690 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62  ional details ab
166a0 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
166b0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
166c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 30 7d 20  .**.** {F12520} 
166d0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
166e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
166f0 69 7a 65 72 28 29 5d 20 6f 76 65 72 72 69 64 65  izer()] override
16700 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  s.**          an
16710 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69 6e 73  y previously ins
16720 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69 7a 65  talled authorize
16730 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 31  r..**.** {F12521
16740 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69  } A NULL authori
16750 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20 6e  zer means that n
16760 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  o authorization.
16770 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
16780 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
16790 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 32 7d 20  .**.** {F12522} 
167a0 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74 68  The default auth
167b0 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e 0a  orizer is NULL..
167c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
167d0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
167e0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
167f0 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
16800 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
16810 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
16820 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
16830 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
16840 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
16850 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
16860 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
16870 64 65 73 20 7b 46 31 32 35 39 30 7d 0a 2a 2a 0a  des {F12590}.**.
16880 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
16890 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
168a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
168b0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
168c0 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
168d0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
168e0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
168f0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
16900 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
16910 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
16920 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
16930 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
16940 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
16950 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
16960 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
16970 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
16980 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
16990 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
169a0 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  n..*/.#define SQ
169b0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
169c0 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
169d0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
169e0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
169f0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
16a00 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
16a10 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
16a20 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
16a30 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
16a40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
16a50 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
16a60 6f 64 65 73 20 7b 46 31 32 35 35 30 7d 0a 2a 2a  odes {F12550}.**
16a70 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
16a80 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
16a90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
16aa0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
16ab0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
16ac0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
16ad0 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
16ae0 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
16af0 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
16b00 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
16b10 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
16b20 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
16b30 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
16b40 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
16b50 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
16b60 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
16b70 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
16b80 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
16b90 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
16ba0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
16bb0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
16bc0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
16bd0 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
16be0 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
16bf0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
16c00 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
16c10 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
16c20 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
16c30 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
16c40 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
16c50 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
16c60 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
16c70 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
16c80 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
16c90 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
16ca0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
16cb0 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74  rameter.  The 5t
16cc0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
16cd0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
16ce0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
16cf0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
16d00 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
16d10 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
16d20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20  if applicable.  
16d30 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
16d40 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
16d50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
16d60 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
16d70 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
16d80 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
16d90 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
16da0 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
16db0 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
16dc0 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
16dd0 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
16de0 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
16df0 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
16e00 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
16e10 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  NTS:.**.** {F125
16e20 35 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70  51} The second p
16e30 61 72 61 6d 65 74 65 72 20 74 6f 20 61 6e 0a 2a  arameter to an.*
16e40 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
16e50 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
16e60 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
16e70 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 61 6c 77  callback] is alw
16e80 61 79 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a  ays an integer.*
16e90 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
16ea0 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72  TE_COPY | author
16eb0 69 7a 65 72 20 63 6f 64 65 5d 20 74 68 61 74 20  izer code] that 
16ec0 73 70 65 63 69 66 69 65 73 20 77 68 61 74 20 61  specifies what a
16ed0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
16ee0 20 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f    is being autho
16ef0 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  rized..**.** {F1
16f00 32 35 35 32 7d 20 54 68 65 20 33 72 64 20 61 6e  2552} The 3rd an
16f10 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
16f20 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
16f30 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
16f40 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
16f50 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c  thorization call
16f60 62 61 63 6b 5d 0a 2a 2a 20 20 20 20 20 20 20 20  back].**        
16f70 20 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65    will be parame
16f80 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
16f90 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 0a  ending on which.
16fa0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
16fb0 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f  ITE_COPY | autho
16fc0 72 69 7a 65 72 20 63 6f 64 65 5d 20 69 73 20 75  rizer code] is u
16fd0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
16fe0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
16ff0 2a 2a 20 7b 46 31 32 35 35 33 7d 20 54 68 65 20  ** {F12553} The 
17000 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
17010 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
17020 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
17030 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
17040 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20  rizer callback] 
17050 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20  is the name.**  
17060 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 64          of the d
17070 61 74 61 62 61 73 65 20 28 65 78 61 6d 70 6c 65  atabase (example
17080 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22  : "main", "temp"
17090 2c 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  , etc.) if appli
170a0 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  cable..**.** {F1
170b0 32 35 35 34 7d 20 54 68 65 20 36 74 68 20 70 61  2554} The 6th pa
170c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
170d0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
170e0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
170f0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
17100 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68 65  callback] is the
17110 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   name.**        
17120 20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d    of the inner-m
17130 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
17140 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
17150 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 20  onsible for.**  
17160 20 20 20 20 20 20 20 20 74 68 65 20 61 63 63 65          the acce
17170 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
17180 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
17190 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
171a0 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 20 20  ectly from.**   
171b0 20 20 20 20 20 20 20 74 6f 70 2d 6c 65 76 65 6c         top-level
171c0 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
171d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
171e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
171f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
17200 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
17210 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
17220 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
17230 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
17240 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
17250 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
17260 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
17270 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
17280 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
17290 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
172a0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
172b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
172c0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
172d0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
172e0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
172f0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
17300 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
17310 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
17320 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
17330 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
17340 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
17350 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17360 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
17370 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
17380 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
17390 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
173a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
173b0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
173c0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
173d0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
173e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
173f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17400 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
17410 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
17420 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
17430 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
17440 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17450 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
17460 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
17470 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
17480 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
17490 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
174a0 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
174b0 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
174c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
174d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
174e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
174f0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
17500 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
17510 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
17520 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17530 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17540 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
17550 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
17560 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
17570 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
17580 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17590 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
175a0 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
175b0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
175c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
175d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
175e0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
175f0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
17600 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
17610 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17620 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17630 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
17640 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
17650 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
17660 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
17670 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
17680 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
17690 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
176a0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
176b0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
176c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
176d0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
176e0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
176f0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
17700 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
17710 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
17720 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
17730 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
17740 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
17750 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17760 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
17770 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
17780 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
17790 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
177a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
177b0 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
177c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
177d0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
177e0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
177f0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
17800 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
17810 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
17820 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
17830 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
17840 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
17850 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
17860 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
17870 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
17880 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
17890 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
178a0 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
178b0 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
178c0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
178d0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
178e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
178f0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
17900 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
17910 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
17920 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
17930 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17940 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
17950 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
17960 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
17970 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
17980 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17990 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
179a0 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
179b0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
179c0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
179d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
179e0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
179f0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
17a00 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
17a10 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17a20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17a30 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
17a40 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
17a50 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
17a60 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
17a70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17a80 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
17a90 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
17aa0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
17ab0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
17ac0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17ad0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
17ae0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
17af0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
17b00 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
17b10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17b20 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
17b30 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
17b40 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
17b50 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
17b60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
17b70 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
17b80 20 20 20 33 31 20 20 20 2f 2a 20 46 75 6e 63 74     31   /* Funct
17b90 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ion Name   NULL 
17ba0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
17bb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
17bc0 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
17bd0 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
17be0 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  ger used */../*.
17bf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
17c00 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
17c10 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31  ng Functions {F1
17c20 32 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  2280}.**.** Thes
17c30 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
17c40 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
17c50 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
17c60 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
17c70 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
17c80 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
17c90 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
17ca0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
17cb0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
17cc0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
17cd0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
17ce0 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
17cf0 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
17d00 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
17d10 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
17d20 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
17d30 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61  ep()]..** The ca
17d40 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
17d50 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
17d60 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   of the SQL stat
17d70 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73  ement text.** as
17d80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
17d90 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
17da0 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  uting.  Addition
17db0 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63  al callbacks occ
17dc0 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
17dd0 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
17de0 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
17df0 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
17e00 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
17e10 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
17e20 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
17e30 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
17e40 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  igger..**.** The
17e50 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
17e60 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
17e70 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
17e80 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
17e90 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
17ea0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
17eb0 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61    The profile ca
17ec0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
17ed0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
17ee0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
17ef0 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
17f00 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
17f10 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
17f20 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
17f30 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a  took to run..**.
17f40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
17f50 72 6f 66 69 6c 65 28 29 20 41 50 49 20 69 73 20  rofile() API is 
17f60 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
17f70 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
17f80 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a  l and.** is subj
17f90 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72  ect to change or
17fa0 20 72 65 6d 6f 76 61 6c 20 69 6e 20 61 20 66 75   removal in a fu
17fb0 74 75 72 65 20 72 65 6c 65 61 73 65 2e 0a 2a 2a  ture release..**
17fc0 0a 2a 2a 20 54 68 65 20 74 72 69 67 67 65 72 20  .** The trigger 
17fd0 72 65 70 6f 72 74 69 6e 67 20 66 65 61 74 75 72  reporting featur
17fe0 65 20 6f 66 20 74 68 65 20 74 72 61 63 65 20 63  e of the trace c
17ff0 61 6c 6c 62 61 63 6b 20 69 73 20 63 6f 6e 73 69  allback is consi
18000 64 65 72 65 64 0a 2a 2a 20 65 78 70 65 72 69 6d  dered.** experim
18010 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62  ental and is sub
18020 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f  ject to change o
18030 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74  r removal in fut
18040 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
18050 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
18060 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
18070 20 61 6c 73 6f 20 61 64 64 20 6e 65 77 20 74 72   also add new tr
18080 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
18090 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a  invocations..**.
180a0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
180b0 2a 0a 2a 2a 20 7b 46 31 32 32 38 31 7d 20 54 68  *.** {F12281} Th
180c0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
180d0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
180e0 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  y [sqlite3_trace
180f0 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ()] is.**       
18100 20 20 20 77 68 65 6e 65 76 65 72 20 61 6e 20 53     whenever an S
18110 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  QL statement fir
18120 73 74 20 62 65 67 69 6e 73 20 74 6f 20 65 78 65  st begins to exe
18130 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  cute and.**     
18140 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 20       whenever a 
18150 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72  trigger subprogr
18160 61 6d 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  am first begins 
18170 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  to run..**.** {F
18180 31 32 32 38 32 7d 20 45 61 63 68 20 63 61 6c 6c  12282} Each call
18190 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
181a0 63 65 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20  ce()] overrides 
181b0 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  the previously.*
181c0 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
181d0 74 65 72 65 64 20 74 72 61 63 65 20 63 61 6c 6c  tered trace call
181e0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  back..**.** {F12
181f0 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63  283} A NULL trac
18200 65 20 63 61 6c 6c 62 61 63 6b 20 64 69 73 61 62  e callback disab
18210 6c 65 73 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a  les tracing..**.
18220 2a 2a 20 7b 46 31 32 32 38 34 7d 20 54 68 65 20  ** {F12284} The 
18230 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
18240 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c  o the trace call
18250 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
18260 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
18270 65 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  e pointer which 
18280 77 61 73 20 74 68 65 20 33 72 64 20 61 72 67 75  was the 3rd argu
18290 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
182a0 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _trace()]..**.**
182b0 20 7b 46 31 32 32 38 35 7d 20 54 68 65 20 73 65   {F12285} The se
182c0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
182d0 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
182e0 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  ack is a.**     
182f0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
18300 61 74 65 64 20 55 54 46 38 20 73 74 72 69 6e 67  ated UTF8 string
18310 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
18320 6f 72 69 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a  original text.**
18330 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
18340 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
18350 73 20 69 74 20 77 61 73 20 70 61 73 73 65 64 20  s it was passed 
18360 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  into [sqlite3_pr
18370 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20  epare_v2()].**  
18380 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 65          or the e
18390 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e  quivalent, or an
183a0 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64   SQL comment ind
183b0 69 63 61 74 69 6e 67 20 74 68 65 20 62 65 67 69  icating the begi
183c0 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  nning.**        
183d0 20 20 6f 66 20 61 20 74 72 69 67 67 65 72 20 73    of a trigger s
183e0 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  ubprogram..**.**
183f0 20 7b 46 31 32 32 38 37 7d 20 54 68 65 20 63 61   {F12287} The ca
18400 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
18410 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73  registered by [s
18420 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
18430 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ] is invoked.** 
18440 20 20 20 20 20 20 20 20 20 61 73 20 65 61 63 68           as each
18450 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
18460 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  inishes..**.** {
18470 46 31 32 32 38 38 7d 20 54 68 65 20 66 69 72 73  F12288} The firs
18480 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
18490 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
184a0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
184b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
184c0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
184d0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  o [sqlite3_profi
184e0 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  le()]..**.** {F1
184f0 32 32 38 39 7d 20 54 68 65 20 73 65 63 6f 6e 64  2289} The second
18500 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
18510 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
18520 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20  ck is a.**      
18530 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
18540 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
18550 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74   that contains t
18560 68 65 20 63 6f 6d 70 6c 65 74 65 20 74 65 78 74  he complete text
18570 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
18580 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
18590 74 20 61 73 20 69 74 20 77 61 73 20 70 72 6f 63  t as it was proc
185a0 65 73 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  essed by [sqlite
185b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a  3_prepare_v2()].
185c0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74  **          or t
185d0 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a  he equivalent..*
185e0 2a 0a 2a 2a 20 7b 46 31 32 32 39 30 7d 20 54 68  *.** {F12290} Th
185f0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
18600 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65  r to the profile
18610 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
18620 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20  estimate.**     
18630 20 20 20 20 20 6f 66 20 74 68 65 20 6e 75 6d 62       of the numb
18640 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  er of nanosecond
18650 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  s of wall-clock 
18660 74 69 6d 65 20 72 65 71 75 69 72 65 64 20 74 6f  time required to
18670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 75 6e  .**          run
18680 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
18690 6e 74 20 66 72 6f 6d 20 73 74 61 72 74 20 74 6f  nt from start to
186a0 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69 64   finish..*/.void
186b0 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
186c0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
186d0 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
186e0 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
186f0 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
18700 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
18710 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
18720 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
18730 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
18740 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
18750 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18760 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
18770 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32  s Callbacks {F12
18780 39 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  910}.**.** This 
18790 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72  routine configur
187a0 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
187b0 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20  nction - the.** 
187c0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
187d0 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f  k - that is invo
187e0 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
187f0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20   during long.** 
18800 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
18810 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
18820 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
18830 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
18840 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
18850 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
18860 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
18870 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
18880 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
18890 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
188a0 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  query..**.** If 
188b0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
188c0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
188d0 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
188e0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
188f0 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
18900 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
18910 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
18920 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
18930 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 64 69  tton on a GUI di
18940 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
18950 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
18960 2a 20 7b 46 31 32 39 31 31 7d 20 54 68 65 20 63  * {F12911} The c
18970 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
18980 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
18990 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
189a0 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20  handler().**    
189b0 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64        is invoked
189c0 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
189d0 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
189e0 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20  g calls to.**   
189f0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
18a00 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  step()]..**.** {
18a10 46 31 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67  F12912} The prog
18a20 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73  ress callback is
18a30 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f   invoked once fo
18a40 72 20 65 76 65 72 79 20 4e 20 76 69 72 74 75 61  r every N virtua
18a50 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61  l.**          ma
18a60 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77  chine opcodes, w
18a70 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
18a80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
18a90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
18aa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65   [sqlite3_progre
18ab0 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61  ss_handler()] ca
18ac0 6c 6c 20 74 68 61 74 20 72 65 67 69 73 74 65 72  ll that register
18ad0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ed.**          t
18ae0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66  he callback.  If
18af0 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
18b00 31 2c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  1, sqlite3_progr
18b10 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a  ess_handler().**
18b20 20 20 20 20 20 20 20 20 20 20 61 63 74 73 20 61            acts a
18b30 73 20 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67  s if a NULL prog
18b40 72 65 73 73 20 68 61 6e 64 6c 65 72 20 68 61 64  ress handler had
18b50 20 62 65 65 6e 20 73 70 65 63 69 66 69 65 64 2e   been specified.
18b60 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 33 7d 20  .**.** {F12913} 
18b70 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  The progress cal
18b80 6c 62 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20  lback itself is 
18b90 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
18ba0 65 20 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20  e third.**      
18bb0 20 20 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20      argument to 
18bc0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
18bd0 5f 68 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a  _handler()..**.*
18be0 2a 20 7b 46 31 32 39 31 34 7d 20 54 68 65 20 66  * {F12914} The f
18bf0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
18c00 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  o sqlite3_progre
18c10 73 73 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20  ss_handler() is 
18c20 61 0a 2a 2a 2a 20 20 20 20 20 20 20 20 20 76 6f  a.***         vo
18c30 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  id pointer passe
18c40 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73  d to the progres
18c50 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  s callback.**   
18c60 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
18c70 65 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20  each time it is 
18c80 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
18c90 46 31 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c  F12915} If a cal
18ca0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
18cb0 65 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e  ep()] results in
18cc0 20 66 65 77 65 72 20 74 68 61 6e 0a 2a 2a 20 20   fewer than.**  
18cd0 20 20 20 20 20 20 20 20 4e 20 6f 70 63 6f 64 65          N opcode
18ce0 73 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  s being executed
18cf0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
18d00 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  en the progress 
18d10 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65  callback is neve
18d20 72 20 69 6e 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d  r invoked. {END}
18d30 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 36 7d 20  .**.** {F12916} 
18d40 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73  Every call to [s
18d50 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
18d60 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20  handler()].**   
18d70 20 20 20 20 20 20 20 6f 76 65 72 77 72 69 74 65         overwrite
18d80 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79  s any previously
18d90 20 72 65 67 69 73 74 65 72 65 64 20 70 72 6f 67   registered prog
18da0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
18db0 0a 2a 2a 20 7b 46 31 32 39 31 37 7d 20 49 66 20  .** {F12917} If 
18dc0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
18dd0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
18de0 20 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72   NULL then no pr
18df0 6f 67 72 65 73 73 0a 2a 2a 20 20 20 20 20 20 20  ogress.**       
18e00 20 20 20 68 61 6e 64 6c 65 72 20 69 73 20 69 6e     handler is in
18e10 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  voked..**.** {F1
18e20 32 39 31 38 7d 20 49 66 20 74 68 65 20 70 72 6f  2918} If the pro
18e30 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
18e40 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
18e50 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68  other than 0, th
18e60 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  en.**          t
18e70 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 61  he behavior is a
18e80 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   if [sqlite3_int
18e90 65 72 72 75 70 74 28 29 5d 20 68 61 64 20 62 65  errupt()] had be
18ea0 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f  en called..*/.vo
18eb0 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
18ec0 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
18ed0 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
18ee0 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
18ef0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18f00 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
18f10 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
18f20 74 69 6f 6e 20 7b 46 31 32 37 30 30 7d 0a 2a 2a  tion {F12700}.**
18f30 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
18f40 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
18f50 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
18f60 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69  whose name is gi
18f70 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69  ven by the.** fi
18f80 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
18f90 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   The filename ar
18fa0 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
18fb0 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
18fc0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
18fd0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
18fe0 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
18ff0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
19000 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
19010 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
19020 5f 6f 70 65 6e 31 36 28 29 2e 20 41 20 5b 64 61  _open16(). A [da
19030 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19040 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
19050 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
19060 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
19070 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
19080 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
19090 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
190a0 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
190b0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
190c0 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
190d0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
190e0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
190f0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
19100 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
19110 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
19120 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
19130 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 49 66  3].** object. If
19140 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
19150 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
19160 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
19170 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
19180 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
19190 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
191a0 73 65 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65  se an error code
191b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
191c0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
191d0 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
191e0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
191f0 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
19200 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
19210 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
19220 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
19230 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e  on of the error.
19240 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  .**.** The defau
19250 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
19260 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
19270 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
19280 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
19290 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
192a0 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
192b0 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
192c0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
192d0 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
192e0 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
192f0 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
19300 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
19310 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
19320 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
19330 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
19340 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
19350 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19360 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
19370 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
19380 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
19390 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
193a0 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
193b0 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
193c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
193d0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
193e0 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
193f0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
19400 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
19410 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
19420 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
19430 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
19440 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
19450 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
19460 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
19470 20 20 54 68 65 20 66 6c 61 67 73 20 70 61 72 61    The flags para
19480 6d 65 74 65 72 20 63 61 6e 20 62 65 20 6f 6e 65  meter can be one
19490 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a   of:.**.** <dl>.
194a0 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f  ** <dt>[SQLITE_O
194b0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
194c0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
194d0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
194e0 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
194f0 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
19500 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
19510 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
19520 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
19530 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  rned.</dd>.**.**
19540 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
19550 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
19560 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
19570 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
19580 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
19590 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
195a0 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
195b0 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
195c0 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
195d0 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
195e0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
195f0 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
19600 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
19610 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
19620 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
19630 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
19640 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
19650 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
19660 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
19670 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
19680 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
19690 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
196a0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
196b0 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
196c0 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20  d is creates it 
196d0 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
196e0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
196f0 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
19700 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
19710 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
19720 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
19730 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
19740 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f  16().</dd>.** </
19750 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
19760 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
19770 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
19780 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
19790 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
197a0 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
197b0 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
197c0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
197d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
197e0 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
197f0 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
19800 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
19810 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
19820 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
19830 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
19840 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d  tion.  This in-m
19850 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
19860 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
19870 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
19880 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
19890 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
198a0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
198b0 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
198c0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
198d0 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
198e0 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
198f0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
19900 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
19910 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
19920 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
19930 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
19940 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
19950 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
19960 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
19970 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
19980 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
19990 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
199a0 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
199b0 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66  iguity..**.** If
199c0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
199d0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
199e0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
199f0 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
19a00 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
19a10 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
19a20 20 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64    This private d
19a30 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
19a40 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
19a50 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
19a60 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
19a70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
19a80 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
19a90 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
19aa0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
19ab0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
19ac0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
19ad0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
19ae0 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
19af0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
19b00 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
19b10 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
19b20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19b30 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49  n should use.  I
19b40 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
19b50 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
19b60 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
19b70 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
19b80 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
19b90 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
19ba0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
19bb0 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
19bc0 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
19bd0 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
19be0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
19bf0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
19c00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
19c10 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
19c20 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
19c30 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
19c40 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
19c50 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
19c60 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
19c70 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
19c80 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
19c90 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
19ca0 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
19cb0 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
19cc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
19cd0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
19ce0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  2()..**.** INVAR
19cf0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
19d00 32 37 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2701} The [sqlit
19d10 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
19d20 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
19d30 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
19d40 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
19d50 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63  ()] interfaces c
19d60 72 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20  reate a new.**  
19d70 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
19d80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73  e connection] as
19d90 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
19da0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 64 61            the da
19db0 74 61 62 61 73 65 20 66 69 6c 65 20 67 69 76 65  tabase file give
19dc0 6e 20 69 6e 20 74 68 65 69 72 20 66 69 72 73 74  n in their first
19dd0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
19de0 2a 20 7b 46 31 32 37 30 32 7d 20 54 68 65 20 66  * {F12702} The f
19df0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
19e00 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
19e10 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20  as UTF-8.**     
19e20 20 20 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65       for [sqlite
19e30 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73  3_open()] and [s
19e40 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19e50 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a  ] and as UTF-16.
19e60 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 74  **          in t
19e70 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
19e80 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65  rder for [sqlite
19e90 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a  3_open16()]..**.
19ea0 2a 2a 20 7b 46 31 32 37 30 33 7d 20 41 20 73 75  ** {F12703} A su
19eb0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
19ec0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
19ed0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
19ee0 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20  3_open16()],.** 
19ef0 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
19f00 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
19f10 77 72 69 74 65 73 20 61 20 70 6f 69 6e 74 65 72  writes a pointer
19f20 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20   to a new.**    
19f30 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
19f40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f  connection] into
19f50 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46   *ppDb..**.** {F
19f60 31 32 37 30 34 7d 20 54 68 65 20 5b 73 71 6c 69  12704} The [sqli
19f70 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
19f80 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
19f90 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
19fa0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
19fb0 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
19fc0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
19fd0 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65 73 73 2c  K] upon success,
19fe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
19ff0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
1a000 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66  error code] on f
1a010 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ailure..**.** {F
1a020 31 32 37 30 36 7d 20 54 68 65 20 64 65 66 61 75  12706} The defau
1a030 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  lt text encoding
1a040 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62   for a new datab
1a050 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  ase created usin
1a060 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
1a070 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f  qlite3_open()] o
1a080 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
1a090 76 32 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54  v2()] will be UT
1a0a0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  F-8..**.** {F127
1a0b0 30 37 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  07} The default 
1a0c0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  text encoding fo
1a0d0 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65  r a new database
1a0e0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
1a0f0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1a100 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69  te3_open16()] wi
1a110 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  ll be UTF-16..**
1a120 0a 2a 2a 20 7b 46 31 32 37 30 39 7d 20 54 68 65  .** {F12709} The
1a130 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46   [sqlite3_open(F
1a140 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69  ,D)] interface i
1a150 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a  s equivalent to.
1a160 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1a170 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1a180 2c 47 2c 30 29 5d 20 77 68 65 72 65 20 74 68 65  ,G,0)] where the
1a190 20 47 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a   G parameter is.
1a1a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
1a1b0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1a1c0 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  TE]|[SQLITE_OPEN
1a1d0 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20  _CREATE]..**.** 
1a1e0 7b 46 31 32 37 31 31 7d 20 49 66 20 74 68 65 20  {F12711} If the 
1a1f0 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  G parameter to [
1a200 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1a210 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69  F,D,G,V)] contai
1a220 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
1a230 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
1a240 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1a250 4c 59 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74  LY] then the dat
1a260 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a  abase is opened.
1a270 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
1a280 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a  reading only..**
1a290 0a 2a 2a 20 7b 46 31 32 37 31 32 7d 20 49 66 20  .** {F12712} If 
1a2a0 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
1a2b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1a2c0 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f  _v2(F,D,G,V)] co
1a2d0 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20  ntains the.**   
1a2e0 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65         bit value
1a2f0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
1a300 41 44 57 52 49 54 45 5d 20 74 68 65 6e 20 74 68  ADWRITE] then th
1a310 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1a320 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ened.**         
1a330 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1a340 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
1a350 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67  , or for reading
1a360 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20   only if the.** 
1a370 20 20 20 20 20 20 20 20 20 66 69 6c 65 20 69 73           file is
1a380 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
1a390 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
1a3a0 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  g system..**.** 
1a3b0 7b 46 31 32 37 31 33 7d 20 49 66 20 74 68 65 20  {F12713} If the 
1a3c0 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  G parameter to [
1a3d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28  sqlite3_open(v2(
1a3e0 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20  F,D,G,V)] omits 
1a3f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1a400 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  bit value [SQLIT
1a410 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61  E_OPEN_CREATE] a
1a420 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  nd the database 
1a430 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  does not.**     
1a440 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20       previously 
1a450 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
1a460 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1a470 2a 2a 20 7b 46 31 32 37 31 34 7d 20 49 66 20 74  ** {F12714} If t
1a480 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74  he G parameter t
1a490 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
1a4a0 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e  v2(F,D,G,V)] con
1a4b0 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  tains the.**    
1a4c0 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20        bit value 
1a4d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
1a4e0 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74  ATE] and the dat
1a4f0 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
1a500 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69  *          previ
1a510 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 74 68 65  ously exist, the
1a520 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  n an attempt is 
1a530 6d 61 64 65 20 74 6f 20 63 72 65 61 74 65 20 61  made to create a
1a540 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  nd.**          i
1a550 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 64 61  nitialize the da
1a560 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  tabase..**.** {F
1a570 31 32 37 31 37 7d 20 49 66 20 74 68 65 20 66 69  12717} If the fi
1a580 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
1a590 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1a5a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1a5b0 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  en16()],.**     
1a5c0 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
1a5d0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 22  _open_v2()] is "
1a5e0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
1a5f0 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20  an private,.**  
1a600 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72 61          ephemera
1a610 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  l, in-memory dat
1a620 61 62 61 73 65 20 69 73 20 63 72 65 61 74 65 64  abase is created
1a630 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
1a640 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ion..**         
1a650 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45   <todo>Is SQLITE
1a660 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c  _OPEN_CREATE|SQL
1a670 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1a680 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20  TE required.**  
1a690 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74          in sqlit
1a6a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74  e3_open_v2()?</t
1a6b0 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  odo>.**.** {F127
1a6c0 31 39 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e  19} If the filen
1a6d0 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  ame is NULL or a
1a6e0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
1a6f0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 0a  then a private,.
1a700 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 65  **          ephe
1a710 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61  meral on-disk da
1a720 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
1a730 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20  reated..**      
1a740 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c      <todo>Is SQL
1a750 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c  ITE_OPEN_CREATE|
1a760 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1a770 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a  WRITE required.*
1a780 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71  *          in sq
1a790 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f  lite3_open_v2()?
1a7a0 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46  </todo>.**.** {F
1a7b0 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61  12721} The [data
1a7c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1a7d0 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c   created by [sql
1a7e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1a7f0 2c 47 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,G,V)].**       
1a800 20 20 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20     will use the 
1a810 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1a820 6a 65 63 74 20 69 64 65 6e 74 69 66 69 65 64 20  ject identified 
1a830 62 79 20 74 68 65 20 56 20 70 61 72 61 6d 65 74  by the V paramet
1a840 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  er,.**          
1a850 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  or the default [
1a860 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1a870 65 63 74 20 69 66 20 56 20 69 73 20 61 20 4e 55  ect if V is a NU
1a880 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1a890 2a 20 7b 46 31 32 37 32 33 7d 20 54 77 6f 20 5b  * {F12723} Two [
1a8a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a8b0 69 6f 6e 20 7c 20 64 61 74 61 62 61 73 65 20 63  ion | database c
1a8c0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c  onnections] will
1a8d0 20 73 68 61 72 65 0a 2a 2a 20 20 20 20 20 20 20   share.**       
1a8e0 20 20 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68     a common cach
1a8f0 65 20 69 66 20 62 6f 74 68 20 77 65 72 65 20 6f  e if both were o
1a900 70 65 6e 65 64 20 77 69 74 68 20 74 68 65 20 73  pened with the s
1a910 61 6d 65 20 56 46 53 20 77 68 69 6c 65 0a 2a 2a  ame VFS while.**
1a920 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1a930 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
1a940 5f 63 61 63 68 65 20 7c 20 73 68 61 72 65 64 20  _cache | shared 
1a950 63 61 63 68 65 20 6d 6f 64 65 20 77 61 73 20 65  cache mode was e
1a960 6e 61 62 6c 65 64 5d 20 61 6e 64 0a 2a 2a 20 20  nabled] and.**  
1a970 20 20 20 20 20 20 20 20 69 66 20 62 6f 74 68 20          if both 
1a980 66 69 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72  filenames compar
1a990 65 20 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65  e equal using me
1a9a0 6d 63 6d 70 28 29 20 61 66 74 65 72 20 68 61 76  mcmp() after hav
1a9b0 69 6e 67 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20  ing been.**     
1a9c0 20 20 20 20 20 70 72 6f 63 65 73 73 65 64 20 62       processed b
1a9d0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
1a9e0 66 73 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61  fs | xFullPathna
1a9f0 6d 65 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  me] method of th
1aa00 65 20 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  e VFS..*/.int sq
1aa10 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
1aa20 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
1aa30 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1aa40 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1aa50 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
1aa60 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1aa70 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1aa80 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1aa90 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
1aaa0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
1aab0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1aac0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1aad0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
1aae0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1aaf0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1ab00 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1ab10 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1ab20 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
1ab30 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
1ab40 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1ab50 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1ab60 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
1ab70 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
1ab80 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1ab90 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
1aba0 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
1abb0 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
1abc0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1abd0 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
1abe0 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
1abf0 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
1ac00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ac10 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
1ac20 4d 65 73 73 61 67 65 73 20 7b 46 31 32 38 30 30  Messages {F12800
1ac30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
1ac40 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e  te3_errcode() in
1ac50 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1ac60 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b  the numeric.** [
1ac70 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75  SQLITE_OK | resu
1ac80 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c  lt code] or [SQL
1ac90 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
1aca0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
1acb0 20 63 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74 68   code].** for th
1acc0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
1acd0 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
1ace0 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  PI call associat
1acf0 65 64 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c 69  ed.** with [sqli
1ad00 74 65 33 5d 20 68 61 6e 64 6c 65 20 27 64 62 27  te3] handle 'db'
1ad10 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
1ad20 20 63 61 6c 6c 20 66 61 69 6c 65 64 20 62 75 74   call failed but
1ad30 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
1ad40 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
1ad50 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
1ad60 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
1ad70 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a  lite3_errcode().
1ad80 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
1ad90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1ada0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
1adb0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1adc0 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
1add0 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
1ade0 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
1adf0 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
1ae00 65 69 74 68 65 72 20 55 54 46 38 20 6f 72 20 55  either UTF8 or U
1ae10 54 46 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  TF16 respectivel
1ae20 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20  y..** Memory to 
1ae30 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
1ae40 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
1ae50 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
1ae60 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
1ae70 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
1ae80 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 77   need to worry w
1ae90 69 74 68 20 66 72 65 65 69 6e 67 20 74 68 65 20  ith freeing the 
1aea0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
1aeb0 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
1aec0 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
1aed0 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
1aee0 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
1aef0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1af00 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
1af10 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
1af20 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ons..**.** INVAR
1af30 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1af40 32 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2801} The [sqlit
1af50 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69  e3_errcode(D)] i
1af60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1af70 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20   the numeric.** 
1af80 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
1af90 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  _OK | result cod
1afa0 65 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e] or.**        
1afb0 20 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f    [SQLITE_IOERR_
1afc0 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
1afd0 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20  result code].** 
1afe0 20 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65           for the
1aff0 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 66   most recently f
1b000 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20  ailed interface 
1b010 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a  call associated.
1b020 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68  **          with
1b030 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b040 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
1b050 7b 46 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71  {F12803} The [sq
1b060 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d  lite3_errmsg(D)]
1b070 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
1b080 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20  rmsg16(D)].**   
1b090 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
1b0a0 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  s return English
1b0b0 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20 74  -language text t
1b0c0 68 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a  hat describes.**
1b0d0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 65 72            the er
1b0e0 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c  ror in the mostl
1b0f0 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65  y recently faile
1b100 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  d interface call
1b110 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e  ,.**          en
1b120 63 6f 64 65 64 20 61 73 20 65 69 74 68 65 72 20  coded as either 
1b130 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 72 65  UTF8 or UTF16 re
1b140 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
1b150 2a 20 7b 46 31 32 38 30 37 7d 20 54 68 65 20 73  * {F12807} The s
1b160 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
1b170 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  by [sqlite3_errm
1b180 73 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  sg()] and [sqlit
1b190 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a  e3_errmsg16()].*
1b1a0 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76  *          are v
1b1b0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e  alid until the n
1b1c0 65 78 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ext SQLite inter
1b1d0 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  face call..**.**
1b1e0 20 7b 46 31 32 38 30 38 7d 20 43 61 6c 6c 73 20   {F12808} Calls 
1b1f0 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  to API routines 
1b200 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75  that do not retu
1b210 72 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65  rn an error code
1b220 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28 65 78  .**          (ex
1b230 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f  ample: [sqlite3_
1b240 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64  data_count()]) d
1b250 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20  o not.**        
1b260 20 20 63 68 61 6e 67 65 20 74 68 65 20 65 72 72    change the err
1b270 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61  or code or messa
1b280 67 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ge returned by.*
1b290 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1b2a0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20  te3_errcode()], 
1b2b0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1b2c0 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
1b2d0 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a  errmsg16()]..**.
1b2e0 2a 2a 20 7b 46 31 32 38 30 39 7d 20 49 6e 74 65  ** {F12809} Inte
1b2f0 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65 20  rfaces that are 
1b300 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  not associated w
1b310 69 74 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a  ith a specific.*
1b320 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
1b330 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b340 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20   (examples:.**  
1b350 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1b360 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b  _mprintf()] or [
1b370 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
1b380 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a  hared_cache()].*
1b390 2a 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f  *          do no
1b3a0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
1b3b0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
1b3c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1b3d0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c  ite3_errcode()],
1b3e0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1b3f0 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
1b400 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f  _errmsg16()]..*/
1b410 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
1b420 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
1b430 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
1b440 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
1b450 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
1b460 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
1b470 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
1b480 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b490 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  : SQL Statement 
1b4a0 4f 62 6a 65 63 74 20 7b 46 31 33 30 30 30 7d 0a  Object {F13000}.
1b4b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
1b4c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1b4d0 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
1b4e0 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
1b4f0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
1b500 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
1b510 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
1b520 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
1b530 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 76  s.** object is v
1b540 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61  ariously known a
1b550 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74  s a "prepared st
1b560 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 20 0a 2a  atement" or a .*
1b570 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
1b580 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
1b590 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
1b5a0 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68  ment"..** .** Th
1b5b0 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
1b5c0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
1b5d0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
1b5e0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
1b5f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
1b600 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
1b610 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1b620 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
1b630 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
1b640 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
1b650 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  Bind values to h
1b660 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 75  ost parameters u
1b670 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71  sing.**      [sq
1b680 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
1b690 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
1b6a0 20 69 6e 74 65 72 66 61 63 65 73 5d 2e 0a 2a 2a   interfaces]..**
1b6b0 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
1b6c0 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
1b6d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
1b6e0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
1b6f0 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
1b700 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  he statement usi
1b710 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
1b720 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
1b730 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
1b740 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
1b750 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
1b760 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
1b770 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
1b780 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
1b790 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
1b7a0 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f  >.**.** Refer to
1b7b0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f   documentation o
1b7c0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74  n individual met
1b7d0 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61  hods above for a
1b7e0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
1b7f0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  ormation..*/.typ
1b800 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
1b810 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
1b820 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
1b830 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
1b840 20 4c 69 6d 69 74 73 20 7b 46 31 32 37 36 30 7d   Limits {F12760}
1b850 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1b860 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
1b870 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
1b880 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
1b890 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
1b8a0 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
1b8b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
1b8c0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
1b8d0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
1b8e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b8f0 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
1b900 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
1b910 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
1b920 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1b930 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
1b940 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
1b950 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
1b960 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
1b970 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
1b980 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
1b990 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
1b9a0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
1b9b0 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
1b9c0 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65   construct.  The
1b9d0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1b9e0 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e  s the old limit.
1b9f0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65  .**.** If the ne
1ba00 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
1ba10 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
1ba20 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
1ba30 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65  nged..** For the
1ba40 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
1ba50 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  of SQLITE_LIMIT_
1ba60 58 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 68  XYZ there is a h
1ba70 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 62 6f 75  ard upper.** bou
1ba80 6e 64 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70  nd set by a comp
1ba90 69 6c 65 2d 74 69 6d 65 20 43 2d 70 72 65 70 72  ile-time C-prepr
1baa0 6f 63 65 73 73 20 6d 61 63 72 6f 20 6e 61 6d 65  ocess macro name
1bab0 64 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a  d SQLITE_MAX_XYZ
1bac0 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
1bad0 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
1bae0 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
1baf0 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d  MAX_".).** Attem
1bb00 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
1bb10 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
1bb20 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
1bb30 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
1bb40 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
1bb50 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c  the hard upper l
1bb60 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20  imit..**.** Run 
1bb70 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
1bb80 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
1bb90 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
1bba0 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
1bbb0 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
1bbc0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
1bbd0 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
1bbe0 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
1bbf0 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
1bc00 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
1bc10 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
1bc20 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
1bc30 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
1bc40 77 65 62 62 72 6f 77 73 65 72 20 74 68 61 74 20  webbrowser that 
1bc50 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
1bc60 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
1bc70 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
1bc80 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
1bc90 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
1bca0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
1bcb0 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
1bcc0 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
1bcd0 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
1bce0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
1bcf0 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
1bd00 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
1bd10 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
1bd20 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
1bd30 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
1bd40 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
1bd50 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
1bd60 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
1bd70 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
1bd80 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
1bd90 2a 2a 20 61 74 74 61 63 68 2e 20 20 44 65 76 65  ** attach.  Deve
1bda0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
1bdb0 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
1bdc0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1bdd0 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
1bde0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
1bdf0 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
1be00 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
1be10 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
1be20 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
1be30 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
1be40 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
1be50 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
1be60 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
1be70 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
1be80 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1be90 72 66 61 63 65 20 69 73 20 63 75 72 72 65 6e 74  rface is current
1bea0 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  ly considered ex
1beb0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
1bec0 73 20 73 75 62 6a 65 63 74 0a 2a 2a 20 74 6f 20  s subject.** to 
1bed0 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61  change or remova
1bee0 6c 20 77 69 74 68 6f 75 74 20 70 72 69 6f 72 20  l without prior 
1bef0 6e 6f 74 69 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e  notice..**.** IN
1bf00 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1bf10 7b 46 31 32 37 36 32 7d 20 41 20 73 75 63 63 65  {F12762} A succe
1bf20 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
1bf30 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43  qlite3_limit(D,C
1bf40 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 0a  ,V)] where V is.
1bf50 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 73 69  **          posi
1bf60 74 69 76 65 20 63 68 61 6e 67 65 73 20 74 68 65  tive changes the
1bf70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 69 6d  .**          lim
1bf80 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f  it on the size o
1bf90 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e  f construct C in
1bfa0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1bfb0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20  ction] D.**     
1bfc0 20 20 20 20 20 74 6f 20 74 68 65 20 6c 65 73 73       to the less
1bfd0 65 72 20 6f 66 20 56 20 61 6e 64 20 74 68 65 20  er of V and the 
1bfe0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1bff0 20 6f 6e 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20   on the size.** 
1c000 20 20 20 20 20 20 20 20 20 6f 66 20 43 20 74 68           of C th
1c010 61 74 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d  at is set at com
1c020 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  pile-time..**.**
1c030 20 7b 46 31 32 37 36 36 7d 20 41 20 73 75 63 63   {F12766} A succ
1c040 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
1c050 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c  sqlite3_limit(D,
1c060 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 73  C,V)] where V is
1c070 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20   negative.**    
1c080 20 20 20 20 20 20 6c 65 61 76 65 73 20 74 68 65        leaves the
1c090 20 73 74 61 74 65 20 6f 66 20 5b 64 61 74 61 62   state of [datab
1c0a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1c0b0 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  D unchanged..**.
1c0c0 2a 2a 20 7b 46 31 32 37 36 39 7d 20 41 20 73 75  ** {F12769} A su
1c0d0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1c0e0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1c0f0 44 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20  D,C,V)] returns 
1c100 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1c110 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d  value of the lim
1c120 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f  it on the size o
1c130 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e  f construct C in
1c140 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
1c150 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c160 74 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 61  tion] D as it wa
1c170 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63  s prior to the c
1c180 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  all..*/.int sqli
1c190 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
1c1a0 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
1c1b0 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
1c1c0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
1c1d0 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
1c1e0 69 65 73 20 7b 46 31 32 37 39 30 7d 0a 2a 2a 20  ies {F12790}.** 
1c1f0 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
1c200 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69   category} {limi
1c210 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
1c220 20 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74   .** These const
1c230 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
1c240 6f 75 73 20 61 73 70 65 63 74 73 20 6f 66 20 61  ous aspects of a
1c250 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c260 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 63  ction].** that c
1c270 61 6e 20 62 65 20 6c 69 6d 69 74 65 64 20 69 6e  an be limited in
1c280 20 73 69 7a 65 20 62 79 20 63 61 6c 6c 73 20 74   size by calls t
1c290 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  o [sqlite3_limit
1c2a0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e  ()]..** The mean
1c2b0 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
1c2c0 6f 75 73 20 6c 69 6d 69 74 73 20 61 72 65 20 61  ous limits are a
1c2d0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1c2e0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
1c2f0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
1c300 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c310 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
1c320 20 61 6e 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f   any.** string o
1c330 72 20 62 6c 6f 62 20 6f 72 20 74 61 62 6c 65 20  r blob or table 
1c340 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  row.<dd>.**.** <
1c350 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c360 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
1c370 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1c380 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
1c390 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  SQL statement.</
1c3a0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1c3b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1c3c0 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
1c3d0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1c3e0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
1c3f0 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
1c400 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
1c410 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53  esult set of a S
1c420 45 4c 45 43 54 20 6f 72 20 74 68 65 20 6d 61 78  ELECT or the max
1c430 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1c440 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
1c450 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
1c460 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
1c470 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
1c480 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1c490 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
1c4a0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1c4b0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
1c4c0 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
1c4d0 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
1c4e0 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  sion.</dd>.**.**
1c4f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1c500 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1c510 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
1c520 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1c530 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
1c540 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
1c550 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
1c560 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1c570 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
1c580 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c590 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1c5a0 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
1c5b0 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
1c5c0 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
1c5d0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1c5e0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
1c5f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1c600 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
1c610 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
1c620 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1c630 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
1c640 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
1c650 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
1c660 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c670 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
1c680 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1c690 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 74 74 61  m number of atta
1c6a0 63 68 65 64 20 64 61 74 61 62 61 73 65 73 2e 3c  ched databases.<
1c6b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1c6c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
1c6d0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
1c6e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1c6f0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
1c700 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
1c710 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c 49  gument to the LI
1c720 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70  KE or.** GLOB op
1c730 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a  erators.</dd>.**
1c740 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1c750 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1c760 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
1c770 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1c780 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73  ber of variables
1c790 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1c7a0 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a  ment that can.**
1c7b0 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a   be bound.</dd>.
1c7c0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
1c7d0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c7e0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
1c7f0 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
1c800 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c810 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
1c820 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
1c830 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c840 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
1c850 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
1c860 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c870 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
1c880 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
1c890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c8a0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
1c8b0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
1c8c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c8d0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
1c8e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c8f0 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
1c900 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
1c910 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
1c920 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
1c930 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
1c940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c950 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
1c960 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
1c970 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
1c980 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
1c990 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
1c9a0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
1c9b0 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      9../*.** CAP
1c9c0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
1c9d0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1c9e0 74 20 7b 46 31 33 30 31 30 7d 0a 2a 2a 0a 2a 2a  t {F13010}.**.**
1c9f0 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
1ca00 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
1ca10 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
1ca20 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
1ca30 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
1ca40 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
1ca50 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a  se routines. .**
1ca60 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
1ca70 67 75 6d 65 6e 74 20 22 64 62 22 20 69 73 20 61  gument "db" is a
1ca80 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
1ca90 65 63 74 69 6f 6e 5d 20 0a 2a 2a 20 6f 62 74 61  ection] .** obta
1caa0 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
1cab0 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  r call to [sqlit
1cac0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1cad0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 0a  ite3_open_v2()].
1cae0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
1caf0 70 65 6e 31 36 28 29 5d 2e 20 0a 2a 2a 20 54 68  pen16()]. .** Th
1cb00 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1cb10 74 20 22 7a 53 71 6c 22 20 69 73 20 74 68 65 20  t "zSql" is the 
1cb20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
1cb30 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
1cb40 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
1cb50 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
1cb60 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
1cb70 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
1cb80 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
1cb90 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
1cba0 65 73 20 55 54 46 2d 38 20 61 6e 64 20 73 71 6c  es UTF-8 and sql
1cbb0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1cbc0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1cbd0 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
1cbe0 73 65 20 55 54 46 2d 31 36 2e 20 7b 45 4e 44 7d  se UTF-16. {END}
1cbf0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42  .**.** If the nB
1cc00 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
1cc10 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 72  less.** than zer
1cc20 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
1cc30 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 66  read up to the f
1cc40 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
1cc50 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 6e 42 79 74  ator..** If nByt
1cc60 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
1cc70 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
1cc80 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1cc90 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73 20 72 65   of .** bytes re
1cca0 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57  ad from zSql.  W
1ccb0 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
1ccc0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
1ccd0 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
1cce0 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
1ccf0 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
1cd00 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
1cd10 74 65 72 20 6f 72 20 0a 2a 2a 20 74 68 65 20 6e  ter or .** the n
1cd20 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
1cd30 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
1cd40 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c  rst. If the call
1cd50 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74  er knows.** that
1cd60 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
1cd70 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
1cd80 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65  inated, then the
1cd90 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a  re is a small.**
1cda0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
1cdb0 61 6e 74 61 67 65 20 74 6f 20 62 65 20 68 61 64  antage to be had
1cdc0 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   by passing an n
1cdd0 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
1cde0 68 61 74 20 0a 2a 2a 20 69 73 20 65 71 75 61 6c  hat .** is equal
1cdf0 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
1ce00 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
1ce10 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
1ce20 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 20 0a 2a 2a  ncluding</i> .**
1ce30 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
1ce40 74 6f 72 20 62 79 74 65 73 2e 7b 45 4e 44 7d 0a  tor bytes.{END}.
1ce50 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73  **.** *pzTail is
1ce60 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
1ce70 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
1ce80 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
1ce90 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 53 51   the.** first SQ
1cea0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
1ceb0 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
1cec0 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c  ines only compil
1ced0 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 73  e the first.** s
1cee0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
1cef0 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
1cf00 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
1cf10 20 77 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a   what remains.**
1cf20 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
1cf30 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  ** *ppStmt is le
1cf40 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
1cf50 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
1cf60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1cf70 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
1cf80 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
1cf90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
1cfa0 4f 72 20 69 66 20 74 68 65 72 65 20 69 73 20 61  Or if there is a
1cfb0 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
1cfc0 20 69 73 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55   is.** set to NU
1cfd0 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75  LL.  If the inpu
1cfe0 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
1cff0 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
1d000 6e 70 75 74 0a 2a 2a 20 69 73 20 61 6e 64 20 65  nput.** is and e
1d010 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 61  mpty string or a
1d020 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
1d030 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
1d040 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 55 31 33 30 31   NULL..** {U1301
1d050 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  8} The calling p
1d060 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
1d070 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
1d080 74 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ting the.** comp
1d090 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
1d0a0 6e 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  nt.** using [sql
1d0b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1d0c0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
1d0d0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
1d0e0 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
1d0f0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
1d100 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
1d110 72 77 69 73 65 20 61 6e 20 0a 2a 2a 20 5b 65 72  rwise an .** [er
1d120 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
1d130 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
1d140 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1d150 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
1d160 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1d170 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
1d180 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
1d190 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
1d1a0 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
1d1b0 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
1d1c0 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
1d1d0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1d1e0 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
1d1f0 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
1d200 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74  ouraged..** In t
1d210 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
1d220 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
1d230 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
1d240 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
1d250 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
1d260 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
1d270 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
1d280 65 20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  e .** original S
1d290 51 4c 20 74 65 78 74 2e 20 7b 45 4e 44 7d 20 54  QL text. {END} T
1d2a0 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
1d2b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d2c0 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
1d2d0 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65  behave a differe
1d2e0 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73  ntly in two ways
1d2f0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
1d300 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64  <li>.** If the d
1d310 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
1d320 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
1d330 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
1d340 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
1d350 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
1d360 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
1d370 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
1d380 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
1d390 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
1d3a0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
1d3b0 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
1d3c0 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68  ain.  If the sch
1d3d0 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20  ema has changed 
1d3e0 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74  in.** a way that
1d3f0 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65   makes the state
1d400 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76  ment no longer v
1d410 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  alid, [sqlite3_s
1d420 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c  tep()] will stil
1d430 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
1d440 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75  ITE_SCHEMA].  Bu
1d450 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67  t unlike the leg
1d460 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 0a 2a  acy behavior, .*
1d470 2a 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  * [SQLITE_SCHEMA
1d480 5d 20 69 73 20 6e 6f 77 20 61 20 66 61 74 61 6c  ] is now a fatal
1d490 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67   error.  Calling
1d4a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1d4b0 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e  pare_v2()] again
1d4c0 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74   will not make t
1d4d0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61  he.** error go a
1d4e0 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20  way.  Note: use 
1d4f0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1d500 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  )] to find the t
1d510 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61  ext.** of the pa
1d520 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74  rsing error that
1d530 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b   results in an [
1d540 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72  SQLITE_SCHEMA] r
1d550 65 74 75 72 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 20  eturn. {END}.** 
1d560 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
1d570 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f  .** When an erro
1d580 72 20 6f 63 63 75 72 73 2c 20 0a 2a 2a 20 5b 73  r occurs, .** [s
1d590 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1d5a0 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
1d5b0 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 20 0a  f the detailed .
1d5c0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
1d5d0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
1d5e0 72 6f 72 20 63 6f 64 65 73 5d 2e 20 0a 2a 2a 20  ror codes]. .** 
1d5f0 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
1d600 69 6f 72 20 77 61 73 20 74 68 61 74 20 5b 73 71  ior was that [sq
1d610 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
1d620 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
1d630 61 20 67 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51  a generic.** [SQ
1d640 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
1d650 6c 74 20 63 6f 64 65 20 61 6e 64 20 79 6f 75 20  lt code and you 
1d660 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
1d670 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
1d680 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1d690 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65  reset()] in orde
1d6a0 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
1d6b0 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
1d6c0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a  f the problem..*
1d6d0 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  * With the "v2" 
1d6e0 70 72 65 70 61 72 65 20 69 6e 74 65 72 66 61 63  prepare interfac
1d6f0 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
1d700 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
1d710 65 20 65 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65  e error is.** re
1d720 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
1d730 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ly..** </li>.** 
1d740 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  </ol>.**.** INVA
1d750 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1d760 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69  13011} The [sqli
1d770 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a  te3_prepare(db,z
1d780 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a  Sql,...)] and.**
1d790 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1d7a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
1d7b0 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65  ,zSql,...)] inte
1d7c0 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74  rfaces interpret
1d7d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1d7e0 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a   text in their z
1d7f0 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73  Sql parameter as
1d800 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46   UTF-8..**.** {F
1d810 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  13012} The [sqli
1d820 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 64 62  te3_prepare16(db
1d830 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a  ,zSql,...)] and.
1d840 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1d850 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1d860 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20  2(db,zSql,...)] 
1d870 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72  interfaces inter
1d880 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  pret the.**     
1d890 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65       text in the
1d8a0 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65  ir zSql paramete
1d8b0 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  r as UTF-16 in t
1d8c0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1d8d0 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  rder..**.** {F13
1d8e0 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74  013} If the nByt
1d8f0 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  e argument to [s
1d900 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1d910 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  2(db,zSql,nByte,
1d920 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
1d930 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e    and its varian
1d940 74 73 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  ts is less than 
1d950 7a 65 72 6f 2c 20 74 68 65 6e 20 53 51 4c 20 74  zero, then SQL t
1d960 65 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ext is.**       
1d970 20 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71     read from zSq
1d980 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
1d990 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
1d9a0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
1d9b0 20 7b 46 31 33 30 31 34 7d 20 49 66 20 74 68 65   {F13014} If the
1d9c0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
1d9d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
1d9e0 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e  are_v2(db,zSql,n
1d9f0 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  Byte,...)].**   
1da00 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76         and its v
1da10 61 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e  ariants is non-n
1da20 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74  egative, then at
1da30 20 6d 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74   most nBytes byt
1da40 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  es.**          S
1da50 51 4c 20 74 65 78 74 20 69 73 20 72 65 61 64 20  QL text is read 
1da60 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a  from zSql..**.**
1da70 20 7b 46 31 33 30 31 35 7d 20 49 6e 20 5b 73 71   {F13015} In [sq
1da80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1da90 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54  (db,zSql,N,P,pzT
1daa0 61 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61  ail)] and its va
1dab0 72 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20  riants.**       
1dac0 20 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69     if the zSql i
1dad0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
1dae0 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  ns more than one
1daf0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
1db00 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 70  *          and p
1db10 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
1db20 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  L, then *pzTail 
1db30 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
1db40 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
1db50 20 20 20 20 66 69 72 73 74 20 62 79 74 65 20 70      first byte p
1db60 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
1db70 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
1db80 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a  tement in zSql..
1db90 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64  **          <tod
1dba0 6f 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54  o>What does *pzT
1dbb0 61 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20  ail point to if 
1dbc0 74 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61  there is one sta
1dbd0 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a  tement?</todo>.*
1dbe0 2a 0a 2a 2a 20 7b 46 31 33 30 31 36 7d 20 41 20  *.** {F13016} A 
1dbf0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
1dc00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
1dc10 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e  are_v2(db,zSql,N
1dc20 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a  ,ppStmt,...)].**
1dc30 20 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65            or one
1dc40 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
1dc50 20 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70   writes into *pp
1dc60 53 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74  Stmt a pointer t
1dc70 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20  o a new.**      
1dc80 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
1dc90 61 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f  atement] or a po
1dca0 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 0a 2a 2a  inter to NULL.**
1dcb0 20 20 20 20 20 20 20 20 20 20 69 66 20 7a 53 71            if zSq
1dcc0 6c 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69  l contains nothi
1dcd0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68  ng other than wh
1dce0 69 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d  itespace or comm
1dcf0 65 6e 74 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31  ents. .**.** {F1
1dd00 33 30 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  3019} The [sqlit
1dd10 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1dd20 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69   interface and i
1dd30 74 73 20 76 61 72 69 61 6e 74 73 20 72 65 74 75  ts variants retu
1dd40 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  rn.**          [
1dd50 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e  SQLITE_OK] or an
1dd60 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
1dd70 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66  ror code] upon f
1dd80 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ailure..**.** {F
1dd90 31 33 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73  13021} Before [s
1dda0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64  qlite3_prepare(d
1ddb0 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53  b,zSql,nByte,ppS
1ddc0 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20  tmt,pzTail)] or 
1ddd0 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
1dde0 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73  variants returns
1ddf0 20 61 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76   an error (any v
1de00 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
1de10 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 0a 2a 2a 20  [SQLITE_OK]).** 
1de20 20 20 20 20 20 20 20 20 20 69 74 20 66 69 72 73           it firs
1de30 74 20 73 65 74 73 20 2a 70 70 53 74 6d 74 20 74  t sets *ppStmt t
1de40 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
1de50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
1de60 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1de70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1de80 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1de90 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1dea0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1deb0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1dec0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
1ded0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1dee0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1def0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1df00 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1df10 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1df20 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1df30 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1df40 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1df50 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1df60 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1df70 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1df80 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1df90 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1dfa0 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
1dfb0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1dfc0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1dfd0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1dfe0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
1dff0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1e000 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
1e010 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1e020 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1e030 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1e040 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1e050 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1e060 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1e070 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1e080 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1e090 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
1e0a0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1e0b0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1e0c0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1e0d0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1e0e0 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
1e0f0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1e100 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1e110 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1e120 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
1e130 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1e140 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
1e150 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1e160 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1e170 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1e180 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1e190 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1e1a0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1e1b0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1e1c0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1e1d0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
1e1e0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1e1f0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1e200 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1e210 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1e220 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1e230 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
1e240 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1e250 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1e260 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1e270 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1e280 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1e290 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
1e2a0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1e2b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1e2c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1e2d0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1e2e0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1e2f0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1e300 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1e310 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1e320 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
1e330 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1e340 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1e350 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1e360 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45  );../*.** CAPIRE
1e370 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
1e380 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33  atement SQL {F13
1e390 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  100}.**.** This 
1e3a0 69 6e 74 65 72 66 61 63 65 20 20 63 61 6e 20 62  interface  can b
1e3b0 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
1e3c0 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
1e3d0 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
1e3e0 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
1e3f0 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
1e400 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e410 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
1e420 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31  NTS:.**.** {F131
1e430 30 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70  01} If the [prep
1e440 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e450 70 61 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20  passed as .**   
1e460 20 20 20 20 20 20 20 74 68 65 20 61 6e 20 61 72         the an ar
1e470 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
1e480 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f  e3_sql()] was co
1e490 6d 70 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20  mpiled.**       
1e4a0 20 20 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e     compiled usin
1e4b0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
1e4c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1e4d0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
1e4e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e4f0 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  6_v2()],.**     
1e500 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74       then [sqlit
1e510 65 33 5f 73 71 6c 28 29 5d 20 66 75 6e 63 74 69  e3_sql()] functi
1e520 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  on returns a poi
1e530 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 20 20 20  nter to a.**    
1e540 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
1e550 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e  nated string con
1e560 74 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20  taining a UTF-8 
1e570 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20  rendering.**    
1e580 20 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69        of the ori
1e590 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d  ginal SQL statem
1e5a0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31  ent..**.** {F131
1e5b0 30 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70  02} If the [prep
1e5c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e5d0 70 61 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20  passed as .**   
1e5e0 20 20 20 20 20 20 20 74 68 65 20 61 6e 20 61 72         the an ar
1e5f0 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
1e600 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f  e3_sql()] was co
1e610 6d 70 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20  mpiled.**       
1e620 20 20 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e     compiled usin
1e630 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
1e640 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a  3_prepare()] or.
1e650 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1e660 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1e670 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ],.**          t
1e680 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c  hen [sqlite3_sql
1e690 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ()] function ret
1e6a0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1e6b0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31  ter..**.** {F131
1e6c0 30 33 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72  03} The string r
1e6d0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1e6e0 74 65 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 76  te3_sql(S)] is v
1e6f0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a  alid until the.*
1e700 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
1e710 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e720 53 20 69 73 20 64 65 6c 65 74 65 64 20 75 73 69  S is deleted usi
1e730 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
1e740 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e  lize(S)]..*/.con
1e750 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1e760 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
1e770 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
1e780 2a 20 43 41 50 49 33 52 45 46 3a 20 20 44 79 6e  * CAPI3REF:  Dyn
1e790 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
1e7a0 61 6c 75 65 20 4f 62 6a 65 63 74 20 20 7b 46 31  alue Object  {F1
1e7b0 35 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  5000}.** KEYWORD
1e7c0 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
1e7d0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
1e7e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1e7f0 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
1e800 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
1e810 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1e820 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
1e830 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
1e840 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
1e850 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
1e860 74 61 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65  table..** SQLite
1e870 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
1e880 70 69 6e 67 20 66 6f 72 20 74 68 65 20 76 61 6c  ping for the val
1e890 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20  ues it stores.  
1e8a0 0a 2a 2a 20 56 61 6c 75 65 73 20 73 74 6f 72 65  .** Values store
1e8b0 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
1e8c0 75 65 20 6f 62 6a 65 63 74 73 20 63 61 6e 20 62  ue objects can b
1e8d0 65 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65 72 73  e.** be integers
1e8e0 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
1e8f0 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
1e900 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
1e910 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
1e920 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1e930 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
1e940 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
1e950 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
1e960 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
1e970 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
1e980 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1e990 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
1e9a0 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
1e9b0 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
1e9c0 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
1e9d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1e9e0 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
1e9f0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
1ea00 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
1ea10 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
1ea20 70 65 63 69 66 69 65 73 20 0a 2a 2a 20 77 68 65  pecifies .** whe
1ea30 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
1ea40 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
1ea50 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1ea60 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
1ea70 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
1ea80 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
1ea90 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
1eaa0 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
1eab0 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20  tex is held.  A 
1eac0 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
1ead0 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
1eae0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1eaf0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
1eb00 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
1eb10 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
1eb20 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1eb30 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
1eb40 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
1eb50 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
1eb60 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
1eb70 28 77 69 74 68 20 53 51 4c 49 54 45 5f 54 48 52  (with SQLITE_THR
1eb80 45 41 44 53 41 46 45 3d 30 20 61 6e 64 20 77 69  EADSAFE=0 and wi
1eb90 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
1eba0 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
1ebb0 69 6e 67 20 30 29 0a 2a 2a 20 74 68 65 6e 20 74  ing 0).** then t
1ebc0 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
1ebd0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  nction between.*
1ebe0 2a 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  * protected and 
1ebf0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
1ec00 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1ec10 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
1ec20 65 0a 2a 2a 20 75 73 65 64 20 69 6e 74 65 72 63  e.** used interc
1ec30 68 61 6e 67 65 61 62 6c 65 2e 20 20 48 6f 77 65  hangeable.  Howe
1ec40 76 65 72 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ver, for maximum
1ec50 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
1ec60 79 20 69 74 0a 2a 2a 20 69 73 20 72 65 63 6f 6d  y it.** is recom
1ec70 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
1ec80 69 63 61 74 69 6f 6e 73 20 6d 61 6b 65 20 74 68  ications make th
1ec90 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
1eca0 74 77 65 65 6e 0a 2a 2a 20 62 65 74 77 65 65 6e  tween.** between
1ecb0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
1ecc0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1ecd0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1ece0 20 65 76 65 6e 20 69 66 0a 2a 2a 20 74 68 65 79   even if.** they
1ecf0 20 61 72 65 20 73 69 6e 67 6c 65 20 74 68 72 65   are single thre
1ed00 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  aded..**.** The 
1ed10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1ed20 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
1ed30 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
1ed40 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
1ed50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1ed60 66 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  f .** [sqlite3_c
1ed70 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 7c  reate_function |
1ed80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
1ed90 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1eda0 6e 73 5d 0a 2a 2a 20 61 72 65 20 70 72 6f 74 65  ns].** are prote
1edb0 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cted..** The sql
1edc0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1edd0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
1ede0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1edf0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
1ee00 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
1ee10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1ee20 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
1ee30 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
1ee40 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
1ee50 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
1ee60 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
1ee70 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 20 20 0a 2a  nd_value()].  .*
1ee80 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
1ee90 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
1eea0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
1eeb0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
1eec0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
1eed0 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
1eee0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1eef0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
1ef00 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
1ef10 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
1ef20 41 50 49 33 52 45 46 3a 20 20 53 51 4c 20 46 75  API3REF:  SQL Fu
1ef30 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
1ef40 62 6a 65 63 74 20 7b 46 31 36 30 30 31 7d 0a 2a  bject {F16001}.*
1ef50 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
1ef60 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
1ef70 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
1ef80 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
1ef90 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
1efa0 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41  ntext object.  A
1efb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
1efc0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
1efd0 2a 20 6f 62 6a 65 63 74 20 69 73 20 61 6c 77 61  * object is alwa
1efe0 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
1eff0 65 72 20 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74  er to .** [sqlit
1f000 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
1f010 6f 6e 20 7c 20 61 70 70 6c 69 63 61 74 69 6f 6e  on | application
1f020 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
1f030 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
1f040 61 70 70 6c 69 63 61 74 69 6f 6e 65 64 2d 64 65  applicationed-de
1f050 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
1f060 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
1f070 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
1f080 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
1f090 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
1f0a0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
1f0b0 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
1f0c0 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
1f0d0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
1f0e0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 0a  ate_context()],.
1f0f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ** [sqlite3_user
1f100 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
1f110 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
1f120 5f 68 61 6e 64 6c 65 28 29 5d 2c 0a 2a 2a 20 5b  _handle()],.** [
1f130 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
1f140 61 74 61 28 29 5d 2c 20 61 6e 64 2f 6f 72 20 5b  ata()], and/or [
1f150 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
1f160 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
1f170 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1f180 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
1f190 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
1f1a0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 42 69 6e  * CAPI3REF:  Bin
1f1b0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
1f1c0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
1f1d0 74 73 20 7b 46 31 33 35 30 30 7d 0a 2a 2a 0a 2a  ts {F13500}.**.*
1f1e0 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72  * In the SQL str
1f1f0 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73  ings input to [s
1f200 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f210 32 28 29 5d 20 61 6e 64 20 69 74 73 0a 2a 2a 20  2()] and its.** 
1f220 76 61 72 69 61 6e 74 73 2c 20 6c 69 74 65 72 61  variants, litera
1f230 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
1f240 65 20 62 79 20 61 20 70 61 72 61 6d 65 74 65 72  e by a parameter
1f250 20 69 6e 20 6f 6e 65 0a 2a 2a 20 6f 66 20 74 68   in one.** of th
1f260 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a  ese forms:.**.**
1f270 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
1f280 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
1f290 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
1f2a0 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
1f2b0 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
1f2c0 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70  >.**.** In the p
1f2d0 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73  arameter forms s
1f2e0 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69  hown above NNN i
1f2f0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
1f300 65 72 61 6c 2c 0a 2a 2a 20 56 56 56 20 61 6c 70  eral,.** VVV alp
1f310 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d  ha-numeric param
1f320 65 74 65 72 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68  eter name..** Th
1f330 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
1f340 65 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  e parameters (al
1f350 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
1f360 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
1f370 0a 2a 2a 20 6f 72 20 22 53 51 4c 20 70 61 72 61  .** or "SQL para
1f380 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
1f390 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
1f3a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1f3b0 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
1f3c0 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54  ed here..**.** T
1f3d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1f3e0 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
1f3f0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
1f400 65 73 20 61 6c 77 61 79 73 0a 2a 2a 20 69 73 20  es always.** is 
1f410 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1f420 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
1f430 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
1f440 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
1f450 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1f460 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
1f470 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  The second.** ar
1f480 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
1f490 64 65 78 20 6f 66 20 74 68 65 20 70 61 72 61 6d  dex of the param
1f4a0 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 20  eter to be set. 
1f4b0 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72  The.** first par
1f4c0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
1f4d0 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20  dex of 1.  When 
1f4e0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
1f4f0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  * parameter is u
1f500 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
1f510 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
1f520 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
1f530 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
1f540 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
1f550 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
1f560 65 6e 63 65 2e 20 0a 2a 2a 20 54 68 65 20 69 6e  ence. .** The in
1f570 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
1f580 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
1f590 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
1f5a0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1f5b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1f5c0 61 6d 65 28 29 5d 20 41 50 49 20 69 66 20 64 65  ame()] API if de
1f5d0 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65  sired.  The inde
1f5e0 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
1f5f0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
1f600 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
1f610 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  ** The NNN value
1f620 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
1f630 20 31 20 61 6e 64 20 74 68 65 20 63 6f 6d 70 69   1 and the compi
1f640 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61 6d  le-time.** param
1f650 65 74 65 72 20 53 51 4c 49 54 45 5f 4d 41 58 5f  eter SQLITE_MAX_
1f660 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
1f670 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
1f680 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  999)..**.** The 
1f690 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
1f6a0 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
1f6b0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
1f6c0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  eter..**.** In t
1f6d0 68 6f 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  hose.** routines
1f6e0 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
1f6f0 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
1f700 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e  s value is the n
1f710 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
1f720 2a 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  * in the paramet
1f730 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
1f740 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
1f750 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  he number of <u>
1f760 62 79 74 65 73 3c 2f 75 3e 0a 2a 2a 20 69 6e 20  bytes</u>.** in 
1f770 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
1f780 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
1f790 72 61 63 74 65 72 73 2e 20 0a 2a 2a 20 49 66 20  racters. .** If 
1f7a0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1f7b0 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
1f7c0 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
1f7d0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
1f7e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1f7f0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
1f800 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
1f810 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ator..**.** The 
1f820 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
1f830 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
1f840 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
1f850 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
1f860 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
1f870 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
1f880 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
1f890 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
1f8a0 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
1f8b0 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
1f8c0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1f8d0 20 69 74 2e 20 49 66 20 74 68 65 20 66 69 66 74   it. If the fift
1f8e0 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
1f8f0 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
1f900 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
1f910 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
1f920 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
1f930 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
1f940 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
1f950 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
1f960 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
1f970 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
1f980 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
1f990 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
1f9a0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
1f9b0 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
1f9c0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
1f9d0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
1f9e0 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
1f9f0 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
1fa00 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
1fa10 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
1fa20 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
1fa30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   The sqlite3_bin
1fa40 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
1fa50 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
1fa60 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
1fa70 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
1fa80 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 7a  with zeros.  A z
1fa90 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
1faa0 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
1fab0 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
1fac0 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
1fad0 64 20 69 74 20 73 69 7a 65 29 20 77 68 69 6c 65  d it size) while
1fae0 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
1faf0 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
1fb00 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
1fb10 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
1fb20 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
1fb30 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
1fb40 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
1fb50 72 69 74 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a  ritten using .**
1fb60 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
1fb70 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20  pen | increment 
1fb80 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
1fb90 65 73 2e 20 41 20 6e 65 67 61 74 69 76 65 0a 2a  es. A negative.*
1fba0 2a 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  * value for the 
1fbb0 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
1fbc0 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
1fbd0 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68  h BLOB..**.** Th
1fbe0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1fbf0 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  () routines must
1fc00 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72   be called after
1fc10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1fc20 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20  pare_v2()] (and 
1fc30 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72  its variants) or
1fc40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1fc50 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65  )] and.** before
1fc60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1fc70 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61  ]..** Bindings a
1fc80 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
1fc90 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
1fca0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
1fcb0 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61  .** Unbound para
1fcc0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
1fcd0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
1fce0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1fcf0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
1fd00 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
1fd10 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63  ss or an error c
1fd20 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69  ode if.** anythi
1fd30 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20  ng goes wrong.  
1fd40 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
1fd50 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
1fd60 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
1fd70 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
1fd80 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e  ange.  [SQLITE_N
1fd90 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
1fda0 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61  d if malloc() fa
1fdb0 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ils..** [SQLITE_
1fdc0 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65  MISUSE] might be
1fdd0 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
1fde0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1fdf0 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76  called on a.** v
1fe00 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74  irtual machine t
1fe10 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67  hat is the wrong
1fe20 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 20   state or which 
1fe30 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e  has already been
1fe40 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44   finalized..** D
1fe50 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75  etection of misu
1fe60 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65  se is unreliable
1fe70 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
1fe80 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e  should not depen
1fe90 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d  d.** on SQLITE_M
1fea0 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20  ISUSE returns.  
1feb0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73  SQLITE_MISUSE is
1fec0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64   intended to ind
1fed0 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67  icate a.** a log
1fee0 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20  ic error in the 
1fef0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75  application.  Fu
1ff00 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1ff10 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
1ff20 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74 68   panic rather th
1ff30 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  an return SQLITE
1ff40 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53  _MISUSE..**.** S
1ff50 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1ff60 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1ff70 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
1ff80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1ff90 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
1ffa0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1ffb0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1ffc0 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
1ffd0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1ffe0 7b 46 31 33 35 30 36 7d 20 54 68 65 20 5b 73 71  {F13506} The [sq
1fff0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
20000 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
20010 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a  mpiler] recogniz
20020 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  es.**          t
20030 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66 6f 72  okens of the for
20040 6d 73 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  ms "?", "?NNN", 
20050 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22 2c 20  "$VVV", ":VVV", 
20060 61 6e 64 20 22 40 56 56 56 22 0a 2a 2a 20 20 20  and "@VVV".**   
20070 20 20 20 20 20 20 20 61 73 20 53 51 4c 20 70 61         as SQL pa
20080 72 61 6d 65 74 65 72 73 2c 20 77 68 65 72 65 20  rameters, where 
20090 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65 71 75 65  NNN is any seque
200a0 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  nce of one or mo
200b0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  re.**          d
200c0 69 67 69 74 73 20 61 6e 64 20 77 68 65 72 65 20  igits and where 
200d0 56 56 56 20 69 73 20 61 6e 79 20 73 65 71 75 65  VVV is any seque
200e0 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  nce of one or mo
200f0 72 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  re .**          
20100 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 63 68 61  alphanumeric cha
20110 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a 22 20  racters or "::" 
20120 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f  optionally follo
20130 77 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  wed by.**       
20140 20 20 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74     a string cont
20150 61 69 6e 69 6e 67 20 6e 6f 20 73 70 61 63 65 73  aining no spaces
20160 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20 77   and contained w
20170 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73 65  ithin parenthese
20180 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 39  s..**.** {F13509
20190 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20 76 61  } The initial va
201a0 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  lue of an SQL pa
201b0 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e  rameter is NULL.
201c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 32 7d 20  .**.** {F13512} 
201d0 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  The index of an 
201e0 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65  "?" SQL paramete
201f0 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65 72 20  r is one larger 
20200 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  than the.**     
20210 20 20 20 20 20 6c 61 72 67 65 73 74 20 69 6e 64       largest ind
20220 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65  ex of SQL parame
20230 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66 74 2c  ter to the left,
20240 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20 20 20   or 1 if.**     
20250 20 20 20 20 20 74 68 65 20 22 3f 22 20 69 73 20       the "?" is 
20260 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  the leftmost SQL
20270 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
20280 2a 20 7b 46 31 33 35 31 35 7d 20 54 68 65 20 69  * {F13515} The i
20290 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e  ndex of an "?NNN
202a0 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  " SQL parameter 
202b0 69 73 20 74 68 65 20 69 6e 74 65 67 65 72 20 4e  is the integer N
202c0 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31  NN..**.** {F1351
202d0 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20  8} The index of 
202e0 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56 56 56  an ":VVV", "$VVV
202f0 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53 51 4c  ", or "@VVV" SQL
20300 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
20310 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61            the sa
20320 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65 78 20  me as the index 
20330 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75  of leftmost occu
20340 72 72 65 6e 63 65 73 20 6f 66 20 74 68 65 20 73  rrences of the s
20350 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
20360 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e  parameter, or on
20370 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20  e more than the 
20380 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 76  largest index ov
20390 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  er all.**       
203a0 20 20 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f     parameters to
203b0 20 74 68 65 20 6c 65 66 74 20 69 66 20 74 68 69   the left if thi
203c0 73 20 69 73 20 74 68 65 20 66 69 72 73 74 20 6f  s is the first o
203d0 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20 20 20 20  ccurrence.**    
203e0 20 20 20 20 20 20 6f 66 20 74 68 69 73 20 70 61        of this pa
203f0 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69 66  rameter, or 1 if
20400 20 74 68 69 73 20 69 73 20 74 68 65 20 6c 65 66   this is the lef
20410 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72 2e  tmost parameter.
20420 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 31 7d 20  .**.** {F13521} 
20430 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  The [sqlite3_pre
20440 70 61 72 65 20 7c 20 53 51 4c 20 73 74 61 74 65  pare | SQL state
20450 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66  ment compiler] f
20460 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ail with.**     
20470 20 20 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f       an [SQLITE_
20480 52 41 4e 47 45 5d 20 65 72 72 6f 72 20 69 66 20  RANGE] error if 
20490 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
204a0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  SQL parameter.**
204b0 20 20 20 20 20 20 20 20 20 20 69 73 20 6c 65 73            is les
204c0 73 20 74 68 61 6e 20 31 20 6f 72 20 67 72 65 61  s than 1 or grea
204d0 74 65 72 20 74 68 61 6e 20 53 51 4c 49 54 45 5f  ter than SQLITE_
204e0 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MAX_VARIABLE_NUM
204f0 42 45 52 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  BER..**.** {F135
20500 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71  24} Calls to [sq
20510 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
20520 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53  | sqlite3_bind(S
20530 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  ,N,V,...)].**   
20540 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65         associate
20550 20 74 68 65 20 76 61 6c 75 65 20 56 20 77 69 74   the value V wit
20560 68 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65  h all SQL parame
20570 74 65 72 73 20 68 61 76 69 6e 67 20 61 6e 0a 2a  ters having an.*
20580 2a 20 20 20 20 20 20 20 20 20 20 69 6e 64 65 78  *          index
20590 20 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b 70 72   of N in the [pr
205a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
205b0 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  ] S..**.** {F135
205c0 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71  27} Calls to [sq
205d0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
205e0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53  | sqlite3_bind(S
205f0 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,N,...)].**     
20600 20 20 20 20 20 6f 76 65 72 72 69 64 65 20 70 72       override pr
20610 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 20 74  ior calls with t
20620 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 6f  he same values o
20630 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a  f S and N..**.**
20640 20 7b 46 31 33 35 33 30 7d 20 42 69 6e 64 69 6e   {F13530} Bindin
20650 67 73 20 65 73 74 61 62 6c 69 73 68 65 64 20 62  gs established b
20660 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
20670 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62  text | sqlite3_b
20680 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  ind(S,...)].**  
20690 20 20 20 20 20 20 20 20 70 65 72 73 69 73 74 20          persist 
206a0 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f 20  across calls to 
206b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
206c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33  )]..**.** {F1353
206d0 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  3} In calls to [
206e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
206f0 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a  b(S,N,V,L,D)],.*
20700 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
20710 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
20720 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  N,V,L,D)], or.**
20730 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
20740 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53  e3_bind_text16(S
20750 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74  ,N,V,L,D)] SQLit
20760 65 20 62 69 6e 64 73 20 74 68 65 20 66 69 72 73  e binds the firs
20770 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  t L.**          
20780 62 79 74 65 73 20 6f 66 20 74 68 65 20 62 6c 6f  bytes of the blo
20790 62 20 6f 72 20 73 74 72 69 6e 67 20 70 6f 69 6e  b or string poin
207a0 74 65 64 20 74 6f 20 62 79 20 56 2c 20 77 68 65  ted to by V, whe
207b0 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  n L.**          
207c0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
207d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 36 7d 20  .**.** {F13536} 
207e0 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
207f0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
20800 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a  ,N,V,L,D)] or.**
20810 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
20820 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53  e3_bind_text16(S
20830 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74  ,N,V,L,D)] SQLit
20840 65 20 62 69 6e 64 73 20 63 68 61 72 61 63 74 65  e binds characte
20850 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  rs.**          f
20860 72 6f 6d 20 56 20 74 68 72 6f 75 67 68 20 74 68  rom V through th
20870 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
20880 72 61 63 74 65 72 20 77 68 65 6e 20 4c 20 69 73  racter when L is
20890 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a   negative..**.**
208a0 20 7b 46 31 33 35 33 39 7d 20 49 6e 20 63 61 6c   {F13539} In cal
208b0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
208c0 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
208d0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
208e0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
208f0 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
20900 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
20910 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
20920 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
20930 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20  ] when D is the 
20940 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20  special.**      
20950 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51      constant [SQ
20960 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 53 51  LITE_STATIC], SQ
20970 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
20980 74 20 74 68 65 20 76 61 6c 75 65 20 56 0a 2a 2a  t the value V.**
20990 20 20 20 20 20 20 20 20 20 20 69 73 20 68 65 6c            is hel
209a0 64 20 69 6e 20 73 74 61 74 69 63 20 75 6e 6d 61  d in static unma
209b0 6e 61 67 65 64 20 73 70 61 63 65 20 74 68 61 74  naged space that
209c0 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65   will not change
209d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75 72  .**          dur
209e0 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
209f0 20 6f 66 20 74 68 65 20 62 69 6e 64 69 6e 67 2e   of the binding.
20a00 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 32 7d 20  .**.** {F13542} 
20a10 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
20a20 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53  ite3_bind_blob(S
20a30 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20  ,N,V,L,D)],.**  
20a40 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
20a50 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
20a60 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,L,D)], or.**   
20a70 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
20a80 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c  bind_text16(S,N,
20a90 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69  V,L,D)] when D i
20aa0 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a  s the special.**
20ab0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61            consta
20ac0 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  nt [SQLITE_TRANS
20ad0 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74 69  IENT], the routi
20ae0 6e 65 20 6d 61 6b 65 73 20 61 20 0a 2a 2a 20 20  ne makes a .**  
20af0 20 20 20 20 20 20 20 20 70 72 69 76 61 74 65 20          private 
20b00 63 6f 70 79 20 6f 66 20 56 20 76 61 6c 75 65 20  copy of V value 
20b10 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
20b20 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 35  s..**.** {F13545
20b30 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
20b40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
20b50 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
20b60 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
20b70 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
20b80 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
20b90 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
20ba0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
20bb0 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44  N,V,L,D)] when D
20bc0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
20bd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66  .**          a f
20be0 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  unction, SQLite 
20bf0 69 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e  invokes that fun
20c00 63 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79  ction to destroy
20c10 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
20c20 20 56 20 76 61 6c 75 65 20 61 66 74 65 72 20 69   V value after i
20c30 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
20c40 73 69 6e 67 20 74 68 65 20 56 20 76 61 6c 75 65  sing the V value
20c50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 38 7d  ..**.** {F13548}
20c60 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
20c70 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
20c80 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68  lob(S,N,V,L)] th
20c90 65 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a  e value bound.**
20ca0 20 20 20 20 20 20 20 20 20 20 69 73 20 61 20 62            is a b
20cb0 6c 6f 62 20 6f 66 20 4c 20 62 79 74 65 73 2c 20  lob of L bytes, 
20cc0 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
20cd0 20 62 6c 6f 62 20 69 66 20 4c 20 69 73 20 6e 65   blob if L is ne
20ce0 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  gative..**.** {F
20cf0 31 33 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20  13551} In calls 
20d00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
20d10 5f 76 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74  _value(S,N,V)] t
20d20 68 65 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61  he V argument ma
20d30 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65  y.**          be
20d40 20 65 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65   either a [prote
20d50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
20d60 75 65 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e  ue] object or an
20d70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e  .**          [un
20d80 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
20d90 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
20da0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
20db0 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
20dc0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
20dd0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
20de0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
20df0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
20e00 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
20e10 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
20e20 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
20e30 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
20e40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
20e50 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
20e60 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
20e70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
20e80 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
20e90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
20ea0 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
20eb0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
20ec0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
20ed0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
20ee0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
20ef0 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  r*, int n, void(
20f00 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
20f10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
20f20 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
20f30 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
20f40 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
20f50 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
20f60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
20f70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
20f80 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
20f90 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
20fa0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
20fb0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
20fc0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
20fd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20fe0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
20ff0 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b 46 31  L Parameters {F1
21000 33 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  3600}.**.** This
21010 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
21020 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
21030 20 6e 75 6d 62 65 72 20 6f 66 20 53 51 4c 20 70   number of SQL p
21040 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 69 6e 20  arameters.** in 
21050 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
21060 6d 65 6e 74 2e 20 20 53 51 4c 20 70 61 72 61 6d  ment.  SQL param
21070 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
21080 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
21090 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
210a0 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
210b0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
210c0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
210d0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
210e0 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
210f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
21100 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
21110 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
21120 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
21130 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63   This routine ac
21140 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
21150 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
21160 6c 61 72 67 65 73 74 20 70 61 72 61 6d 65 74 65  largest paramete
21170 72 2e 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 66 6f  r..** For all fo
21180 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
21190 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
211a0 73 70 6f 6e 64 20 74 6f 20 74 68 65 20 6e 75 6d  spond to the num
211b0 62 65 72 20 6f 66 0a 2a 2a 20 75 6e 69 71 75 65  ber of.** unique
211c0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
211d0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
211e0 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64  he ?NNN are used
211f0 2c 20 74 68 65 72 65 20 6d 61 79 0a 2a 2a 20 62  , there may.** b
21200 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
21210 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  st..**.** See al
21220 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
21230 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
21240 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
21250 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
21260 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
21270 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
21280 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
21290 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
212a0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
212b0 33 36 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3601} The [sqlit
212c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
212d0 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65  r_count(S)] inte
212e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
212f0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 61            the la
21300 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61  rgest index of a
21310 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ll SQL parameter
21320 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  s in the.**     
21330 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
21340 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20  tatement] S, or 
21350 30 20 69 66 20 53 0a 2a 2a 20 20 20 20 20 20 20  0 if S.**       
21360 20 20 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53     contains no S
21370 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  QL parameters..*
21380 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
21390 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
213a0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
213b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
213c0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
213d0 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b 46 31  st Parameter {F1
213e0 33 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  3620}.**.** This
213f0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
21400 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
21410 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d  e name of the n-
21420 74 68 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  th.** SQL parame
21430 74 65 72 20 69 6e 20 61 20 5b 70 72 65 70 61 72  ter in a [prepar
21440 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
21450 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  * SQL parameters
21460 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
21470 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
21480 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
21490 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
214a0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
214b0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
214c0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
214d0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
214e0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
214f0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
21500 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
21510 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
21520 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
21530 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
21540 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65   name..** Parame
21550 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
21560 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
21570 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
21580 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a   have no name..*
21590 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68  *.** The first h
215a0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
215b0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
215c0 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66   not 0..**.** If
215d0 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20   the value n is 
215e0 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
215f0 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61  if the n-th para
21600 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
21610 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
21620 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
21630 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
21640 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
21650 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
21660 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
21670 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
21680 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
21690 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
216a0 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
216b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
216c0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
216d0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
216e0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
216f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
21700 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
21710 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
21720 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
21730 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
21740 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
21750 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
21760 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
21770 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32  TS:.**.** {F1362
21780 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
21790 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
217a0 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
217b0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
217c0 20 20 20 20 20 20 20 20 61 20 55 54 46 2d 38 20          a UTF-8 
217d0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
217e0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
217f0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a   parameter in.**
21800 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
21810 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
21820 20 68 61 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c   having index N,
21830 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
21840 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73  NULL if there is
21850 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65   no SQL paramete
21860 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 6f  r with index N o
21870 72 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  r if the.**     
21880 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 77       parameter w
21890 69 74 68 20 69 6e 64 65 78 20 4e 20 69 73 20 61  ith index N is a
218a0 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61  n anonymous para
218b0 6d 65 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f  meter "?"..*/.co
218c0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
218d0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
218e0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
218f0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
21900 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
21910 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
21920 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
21930 6d 65 20 7b 46 31 33 36 34 30 7d 0a 2a 2a 0a 2a  me {F13640}.**.*
21940 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64  * Return the ind
21950 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
21960 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
21970 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69   name.  The.** i
21980 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
21990 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
219a0 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
219b0 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
219c0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
219d0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
219e0 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72  _bind()].  A zer
219f0 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
21a00 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
21a10 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
21a20 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74  nd.  The paramet
21a30 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
21a40 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
21a50 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
21a60 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
21a70 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
21a80 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
21a90 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
21aa0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
21ab0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
21ac0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
21ad0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
21ae0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
21af0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
21b00 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
21b10 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
21b20 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
21b30 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
21b40 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
21b50 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  641} The [sqlite
21b60 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
21b70 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74  _index(S,N)] int
21b80 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
21b90 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69  *          the i
21ba0 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61  ndex of SQL para
21bb0 6d 65 74 65 72 20 69 6e 20 5b 70 72 65 70 61 72  meter in [prepar
21bc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
21bd0 20 20 20 20 20 20 20 20 20 20 53 20 77 68 6f 73            S whos
21be0 65 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20 74  e name matches t
21bf0 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  he UTF-8 string 
21c00 4e 2c 20 6f 72 20 30 20 69 66 20 74 68 65 72 65  N, or 0 if there
21c10 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
21c20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74  no match..*/.int
21c30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
21c40 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
21c50 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
21c60 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
21c70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21c80 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
21c90 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
21ca0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31  ed Statement {F1
21cb0 33 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74  3660}.**.** Cont
21cc0 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
21cd0 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
21ce0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
21cf0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65 73   does not.** res
21d00 65 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  et the [sqlite3_
21d10 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
21d20 69 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b  ings] on a .** [
21d30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21d40 6e 74 5d 2e 20 20 55 73 65 20 74 68 69 73 20 72  nt].  Use this r
21d50 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73  outine to.** res
21d60 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
21d70 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
21d80 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
21d90 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 36 31 7d  :.**.** {F13661}
21da0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   The [sqlite3_cl
21db0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d  ear_bindings(S)]
21dc0 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
21dd0 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  s all.**        
21de0 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20    SQL parameter 
21df0 62 69 6e 64 69 6e 67 73 20 69 6e 20 5b 70 72 65  bindings in [pre
21e00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21e10 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62   S.**          b
21e20 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ack to NULL..*/.
21e30 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
21e40 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
21e50 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
21e60 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
21e70 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
21e80 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46   A Result Set {F
21e90 31 33 37 31 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74  13710}.**.** Ret
21ea0 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
21eb0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
21ec0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
21ed0 72 6e 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  rned 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 0a 2a 2a 20  ne returns 0.** 
21f10 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
21f20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL 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 0a 2a 2a 20  n data (for .** 
21f50 65 78 61 6d 70 6c 65 20 61 6e 20 55 50 44 41 54  example an UPDAT
21f60 45 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  E)..**.** INVARI
21f70 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
21f80 37 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  711} The [sqlite
21f90 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53  3_column_count(S
21fa0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
21fb0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
21fc0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  of.**          c
21fd0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
21fe0 73 75 6c 74 20 73 65 74 20 67 65 6e 65 72 61 74  sult set generat
21ff0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
22000 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
22010 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72  statement] S, or
22020 20 30 20 69 66 20 53 20 64 6f 65 73 20 6e 6f 74   0 if S does not
22030 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 20 20 20   generate.**    
22040 20 20 20 20 20 20 61 20 72 65 73 75 6c 74 20 73        a result s
22050 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
22060 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
22070 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
22080 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
22090 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
220a0 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
220b0 53 65 74 20 7b 46 31 33 37 32 30 7d 0a 2a 2a 0a  Set {F13720}.**.
220c0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
220d0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
220e0 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
220f0 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
22100 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
22110 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45  lt set of a SELE
22120 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  CT statement.  T
22130 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
22140 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
22150 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
22160 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
22170 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
22180 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
22190 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
221a0 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
221b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
221c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
221d0 2a 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20  * UTF16 string. 
221e0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
221f0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
22200 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22210 6e 74 5d 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  nt] that impleme
22220 6e 74 73 20 74 68 65 20 53 45 4c 45 43 54 20 73  nts the SELECT s
22230 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  tatement..** The
22240 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
22250 72 20 69 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20  r is the column 
22260 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66  number.  The lef
22270 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
22280 0a 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a  .** number 0..**
22290 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
222a0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
222b0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
222c0 69 74 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b 70  ither the .** [p
222d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
222e0 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  t] is destroyed 
222f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
22300 6c 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e  lize()].** or un
22310 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
22320 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
22330 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
22340 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
22350 28 29 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d  ().** on the sam
22360 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
22370 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
22380 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
22390 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
223a0 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
223b0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
223c0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
223d0 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
223e0 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
223f0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
22400 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
22410 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f  **.** The name o
22420 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
22430 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
22440 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
22450 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
22460 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
22470 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
22480 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
22490 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
224a0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
224b0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
224c0 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
224d0 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
224e0 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
224f0 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
22500 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
22510 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32  TS:.**.** {F1372
22520 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  1} A successful 
22530 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
22540 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
22550 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20  n_name(S,N)].** 
22560 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
22570 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
22580 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
22590 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  of the Nth colum
225a0 6e 20 28 77 68 65 72 65 20 30 20 69 73 20 74 68  n (where 0 is th
225b0 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
225c0 6d 6e 29 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  mn) for the.**  
225d0 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73          result s
225e0 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
225f0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20  statement] S as 
22600 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  a.**          ze
22610 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
22620 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
22630 2a 20 7b 46 31 33 37 32 33 7d 20 41 20 73 75 63  * {F13723} A suc
22640 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
22650 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
22660 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
22670 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  (S,N)].**       
22680 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74     interface ret
22690 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  urns the name.**
226a0 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
226b0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65   Nth column (whe
226c0 72 65 20 30 20 69 73 20 74 68 65 20 6c 65 66 74  re 0 is the left
226d0 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f  -most column) fo
226e0 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
226f0 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20    result set of 
22700 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22710 65 6e 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20  ent] S as a.**  
22720 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
22730 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 73  minated UTF-16 s
22740 74 72 69 6e 67 20 69 6e 20 74 68 65 20 6e 61 74  tring in the nat
22750 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
22760 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 34 7d 20 54  **.** {F13724} T
22770 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
22780 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b  mn_name()] and [
22790 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
227a0 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  ame16()].**     
227b0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20       interfaces 
227c0 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f  return a NULL po
227d0 69 6e 74 65 72 20 69 66 20 74 68 65 79 20 61 72  inter if they ar
227e0 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20  e unable to.**  
227f0 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65          allocate
22800 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
22810 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74  their normal ret
22820 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a  urn strings..**.
22830 2a 2a 20 7b 46 31 33 37 32 35 7d 20 49 66 20 74  ** {F13725} If t
22840 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
22850 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
22860 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a  n_name(S,N)] or.
22870 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
22880 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
22890 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20  16(S,N)] is out 
228a0 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74  of range, then t
228b0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  he.**          i
228c0 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e  nterfaces return
228d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
228e0 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 33 37 32 36 7d  .** .** {F13726}
228f0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
22900 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
22910 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c  3_column_name(S,
22920 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  N)] and.**      
22930 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
22940 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  umn_name16(S,N)]
22950 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
22960 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20   the next.**    
22970 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69        call to ei
22980 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74  ther routine wit
22990 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64  h the same S and
229a0 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a   N parameters.**
229b0 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74            or unt
229c0 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  il [sqlite3_fina
229d0 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c  lize(S)] is call
229e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32  ed..**.** {F1372
229f0 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74  7} When a result
22a00 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45   column of a [SE
22a10 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
22a20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20  contains.**     
22a30 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73       an AS claus
22a40 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  e, the name of t
22a50 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  hat column is th
22a60 65 20 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20  e identifier.** 
22a70 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20           to the 
22a80 72 69 67 68 74 20 6f 66 20 74 68 65 20 41 53 20  right of the AS 
22a90 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73  keyword..*/.cons
22aa0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
22ab0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
22ac0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
22ad0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
22ae0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
22af0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
22b00 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
22b10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
22b20 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
22b30 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 46   Query Result {F
22b40 31 33 37 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  13740}.**.** The
22b50 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
22b60 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
22b70 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f  etermine what co
22b80 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20  lumn of what.** 
22b90 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64  table in which d
22ba0 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74  atabase a result
22bb0 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61   of a SELECT sta
22bc0 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f  tement comes fro
22bd0 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f  m..** The name o
22be0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
22bf0 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
22c00 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
22c10 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
22c20 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 73   UTF8 or UTF16 s
22c30 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74  tring.  The _dat
22c40 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
22c50 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
22c60 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
22c70 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
22c80 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
22c90 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
22ca0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
22cb0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
22cc0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
22cd0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
22ce0 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
22cf0 69 6c 0a 2a 2a 20 74 68 65 20 5b 70 72 65 70 61  il.** the [prepa
22d00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
22d10 73 20 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e  s destroyed usin
22d20 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  g.** [sqlite3_fi
22d30 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
22d40 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
22d50 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
22d60 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
22d70 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
22d80 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  oding..**.** The
22d90 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
22da0 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
22db0 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
22dc0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
22dd0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
22de0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54   column..**.** T
22df0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
22e00 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69  t to the followi
22e10 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70  ng calls is a [p
22e20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22e30 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  t]..** These fun
22e40 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
22e50 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
22e60 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
22e70 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 74  eturned by .** t
22e80 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
22e90 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
22ea0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
22eb0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ument..**.** If 
22ec0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
22ed0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
22ee0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
22ef0 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72 20  xpression.** or 
22f00 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
22f10 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
22f20 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
22f30 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a  these functions.
22f40 2a 2a 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 20  ** return NULL. 
22f50 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d   These routine m
22f60 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
22f70 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
22f80 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
22f90 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 4f  error occurs.  O
22fa0 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
22fb0 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e 61  eturn the .** na
22fc0 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
22fd0 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
22fe0 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68  le and column th
22ff0 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a  at query result.
23000 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  ** column was ex
23010 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
23020 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20  .** As with all 
23030 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
23040 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78  s, those postfix
23050 65 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  ed with "16" ret
23060 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
23070 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74  coded strings, t
23080 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
23090 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
230a0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
230b0 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
230c0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
230d0 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
230e0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
230f0 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  .** SQLITE_ENABL
23100 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
23110 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  A preprocessor s
23120 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
23130 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 0a 2a 2a  *.** {U13751}.**
23140 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
23150 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
23160 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
23170 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
23180 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
23190 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
231a0 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
231b0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
231c0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
231d0 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
231e0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
231f0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 31  S:.**.** {F13741
23200 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
23210 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
23220 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
23230 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
23240 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
23250 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  he UTF-8 zero-te
23260 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
23270 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
23280 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a  om which the .**
23290 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
232a0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b  sult column of [
232b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
232c0 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20  nt] S .**       
232d0 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c     is extracted,
232e0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
232f0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
23300 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
23310 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73   general express
23320 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65  ion or if unable
23330 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
23340 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ory.**          
23350 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d  to store the nam
23360 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a  e..**          .
23370 2a 2a 20 7b 46 31 33 37 34 32 7d 20 54 68 65 20  ** {F13742} The 
23380 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
23390 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
233a0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
233b0 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
233c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55  *          the U
233d0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
233e0 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
233f0 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
23400 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
23410 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68  database from wh
23420 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ich the .**     
23430 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20       Nth result 
23440 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61  column of [prepa
23450 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
23460 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73   .**          is
23470 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
23480 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
23490 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a  olumn of S is a.
234a0 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65  **          gene
234b0 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  ral expression o
234c0 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
234d0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a  llocate memory.*
234e0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74  *          to st
234f0 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
23500 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46            .** {F
23510 31 33 37 34 33 7d 20 54 68 65 20 5b 73 71 6c 69  13743} The [sqli
23520 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
23530 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _name(S,N)] inte
23540 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
23550 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
23560 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d   the UTF-8 zero-
23570 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
23580 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66 72 6f  of the table fro
23590 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20  m which the .** 
235a0 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73           Nth res
235b0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70  ult column of [p
235c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
235d0 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20  t] S .**        
235e0 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20    is extracted, 
235f0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
23600 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
23610 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
23620 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
23630 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20  on or if unable 
23640 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
23650 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ry.**          t
23660 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
23670 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a  ..**          .*
23680 2a 20 7b 46 31 33 37 34 34 7d 20 54 68 65 20 5b  * {F13744} The [
23690 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
236a0 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  able_name16(S,N)
236b0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
236c0 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
236d0 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31         the UTF-1
236e0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
236f0 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
23700 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
23710 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
23720 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  e from which the
23730 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74   .**          Nt
23740 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
23750 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
23760 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20  tement] S .**   
23770 20 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63         is extrac
23780 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
23790 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
237a0 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  f S is a.**     
237b0 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70       general exp
237c0 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e  ression or if un
237d0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
237e0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20   memory.**      
237f0 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65      to store the
23800 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20   name..**       
23810 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 35 7d 20     .** {F13745} 
23820 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
23830 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
23840 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
23850 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
23860 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55  *          the U
23870 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
23880 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
23890 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72   table column fr
238a0 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a  om which the .**
238b0 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
238c0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b  sult column of [
238d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
238e0 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20  nt] S .**       
238f0 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c     is extracted,
23900 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
23910 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
23920 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
23930 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73   general express
23940 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65  ion or if unable
23950 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
23960 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ory.**          
23970 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d  to store the nam
23980 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a  e..**          .
23990 2a 2a 20 7b 46 31 33 37 34 36 7d 20 54 68 65 20  ** {F13746} The 
239a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
239b0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c  origin_name16(S,
239c0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
239d0 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
239e0 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
239f0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
23a00 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
23a10 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
23a20 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
23a30 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20  ble column from 
23a40 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20  which the .**   
23a50 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c         Nth resul
23a60 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65  t column of [pre
23a70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23a80 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   S .**          
23a90 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72  is extracted, or
23aa0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
23ab0 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
23ac0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65  a.**          ge
23ad0 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
23ae0 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
23af0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
23b00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
23b10 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
23b20 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20  **          .** 
23b30 7b 46 31 33 37 34 38 7d 20 54 68 65 20 72 65 74  {F13748} The ret
23b40 75 72 6e 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a  urn values from.
23b50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
23b60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
23b70 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e  base_name|column
23b80 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
23b90 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20  aces].**        
23ba0 20 20 61 72 65 20 76 61 6c 69 64 0a 2a 2a 20 20    are valid.**  
23bb0 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20          for the 
23bc0 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20  lifetime of the 
23bd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23be0 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ent].**         
23bf0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e   or until the en
23c00 63 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65  coding is change
23c10 64 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74  d by another met
23c20 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20  adata.**        
23c30 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c    interface call
23c40 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72   for the same pr
23c50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23c60 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
23c70 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
23c80 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 20 49  **.** {U13751} I
23c90 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
23ca0 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
23cb0 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20  r more.**       
23cc0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
23cd0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
23ce0 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61  |column metadata
23cf0 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
23d00 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
23d10 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
23d20 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
23d30 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20  t column.**     
23d40 20 20 20 20 20 61 74 20 74 68 65 20 73 61 6d 65       at the same
23d50 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
23d60 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
23d70 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
23d80 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
23d90 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
23da0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
23db0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
23dc0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
23dd0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
23de0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
23df0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
23e00 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23e10 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
23e20 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
23e30 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
23e40 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
23e50 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
23e60 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
23e70 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
23e80 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
23e90 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
23ea0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
23eb0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
23ec0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
23ed0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
23ee0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23ef0 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
23f00 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
23f10 20 52 65 73 75 6c 74 20 7b 46 31 33 37 36 30 7d   Result {F13760}
23f20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
23f30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
23f40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23f50 65 6e 74 5d 2e 20 0a 2a 2a 20 49 66 20 74 68 69  ent]. .** If thi
23f60 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
23f70 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
23f80 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
23f90 6c 75 6d 6e 20 6f 66 20 74 68 65 20 0a 2a 2a 20  lumn of the .** 
23fa0 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
23fb0 73 65 74 20 6f 66 20 74 68 61 74 20 53 45 4c 45  set of that SELE
23fc0 43 54 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  CT is a table co
23fd0 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
23fe0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
23ff0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
24000 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
24010 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
24020 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
24030 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63  d.  If the Nth c
24040 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
24050 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
24060 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
24070 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
24080 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
24090 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65  returned..** The
240a0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
240b0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
240c0 20 65 6e 63 6f 64 65 64 2e 20 20 7b 45 4e 44 7d   encoded.  {END}
240d0 20 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65   .** For example
240e0 2c 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  , in the databas
240f0 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
24100 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
24110 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
24120 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** And the follo
24130 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  wing statement c
24140 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
24150 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
24160 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
24170 54 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  Then this routin
24180 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
24190 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
241a0 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
241b0 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 6c  nd.** result col
241c0 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
241d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
241e0 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
241f0 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69  ult column.** (i
24200 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ==0)..**.** SQLi
24210 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
24220 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
24230 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73    So just becaus
24240 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
24250 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
24260 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
24270 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
24280 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
24290 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
242a0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
242b0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
242c0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
242d0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
242e0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
242f0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
24300 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a   static.  Type.*
24310 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
24320 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
24330 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
24340 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
24350 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
24360 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a  those values..**
24370 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
24380 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 31 7d 20 20  **.** {F13761}  
24390 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
243a0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
243b0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c  lumn_decltype(S,
243c0 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  N)].**          
243d0 20 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d   returns a zero-
243e0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
243f0 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
24400 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ng the.**       
24410 20 20 20 20 74 68 65 20 64 65 63 6c 61 72 65 64      the declared
24420 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65   datatype of the
24430 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
24440 61 74 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20  at appears.**   
24450 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20 4e          as the N
24460 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65  th column (numbe
24470 72 65 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74  red from 0) of t
24480 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f  he result set to
24490 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
244a0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
244b0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20  ement] S..**.** 
244c0 7b 46 31 33 37 36 32 7d 20 20 41 20 73 75 63 63  {F13762}  A succ
244d0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
244e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
244f0 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a  ecltype16(S,N)].
24500 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
24510 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  urns a zero-term
24520 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61  inated UTF-16 na
24530 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
24540 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
24550 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74      containing t
24560 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61  he declared data
24570 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
24580 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70  e column that ap
24590 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  pears.**        
245a0 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f     as the Nth co
245b0 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66  lumn (numbered f
245c0 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65  rom 0) of the re
245d0 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a  sult set to the.
245e0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72  **           [pr
245f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24600 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ] S..**.** {F137
24610 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73  63}  If N is les
24620 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73  s than 0 or N is
24630 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72   greater than or
24640 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20   equal to.**    
24650 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65         the numbe
24660 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
24670 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24680 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20  ent] S.**       
24690 20 20 20 20 6f 72 20 69 66 20 74 68 65 20 4e 74      or if the Nt
246a0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
246b0 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
246c0 72 20 73 75 62 71 75 65 72 79 20 72 61 74 68 65  r subquery rathe
246d0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  r.**           t
246e0 68 61 6e 20 61 20 74 61 62 6c 65 20 63 6f 6c 75  han a table colu
246f0 6d 6e 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  mn or if a memor
24700 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
24710 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  lure.**         
24720 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20    occurs during 
24730 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73  encoding convers
24740 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  ions, then.**   
24750 20 20 20 20 20 20 20 20 63 61 6c 6c 73 20 74 6f          calls to
24760 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24770 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20  _decltype(S,N)] 
24780 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
24790 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
247a0 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d  decltype16(S,N)]
247b0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f   return NULL..*/
247c0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
247d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
247e0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
247f0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
24800 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
24810 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
24820 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
24830 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50 49 33  );../* .** CAPI3
24840 52 45 46 3a 20 20 45 76 61 6c 75 61 74 65 20 41  REF:  Evaluate A
24850 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
24860 7b 46 31 33 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41  {F13200}.**.** A
24870 66 74 65 72 20 61 6e 20 5b 70 72 65 70 61 72 65  fter an [prepare
24880 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
24890 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 77   been prepared w
248a0 69 74 68 20 61 20 63 61 6c 6c 0a 2a 2a 20 74 6f  ith a call.** to
248b0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
248c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
248d0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
248e0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 6f  re16_v2()] or to
248f0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c   one of.** the l
24900 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 73  egacy interfaces
24910 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24920 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
24930 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a  _prepare16()],.*
24940 2a 20 74 68 65 6e 20 74 68 69 73 20 66 75 6e 63  * then this func
24950 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 63 61 6c  tion must be cal
24960 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
24970 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
24980 65 20 74 68 65 20 0a 2a 2a 20 73 74 61 74 65 6d  e the .** statem
24990 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
249a0 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
249b0 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 73  havior of this s
249c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
249d0 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
249e0 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
249f0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
24a00 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
24a10 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
24a20 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
24a30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
24a40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
24a50 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
24a60 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
24a70 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
24a80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
24a90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
24aa0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
24ab0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
24ac0 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
24ad0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
24ae0 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
24af0 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
24b00 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
24b10 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
24b20 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
24b30 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  d..**.** In the 
24b40 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
24b50 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
24b60 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
24b70 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
24b80 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e   .** [SQLITE_DON
24b90 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
24ba0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
24bb0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
24bc0 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  USE]..** With th
24bd0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
24be0 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
24bf0 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  er [SQLITE_OK | 
24c00 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20  result code].** 
24c10 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
24c20 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
24c30 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6d 69   result code] mi
24c40 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
24c50 61 73 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  as.** well..**.*
24c60 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
24c70 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
24c80 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
24c90 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
24ca0 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
24cb0 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
24cc0 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
24cd0 62 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  b.  If the state
24ce0 6d 65 6e 74 20 69 73 20 61 20 43 4f 4d 4d 49 54  ment is a COMMIT
24cf0 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
24d00 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
24d10 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
24d20 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
24d30 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
24d40 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
24d50 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
24d60 61 20 43 4f 4d 4d 49 54 20 61 6e 64 20 6f 63 63  a COMMIT and occ
24d70 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20  urs within a.** 
24d80 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
24d90 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
24da0 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
24db0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
24dc0 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
24dd0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ng..**.** [SQLIT
24de0 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
24df0 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
24e00 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
24e10 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
24e20 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
24e30 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
24e40 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
24e50 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
24e60 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
24e70 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
24e80 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
24e90 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
24ea0 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
24eb0 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
24ec0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
24ed0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
24ee0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
24ef0 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
24f00 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
24f10 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  en .** [SQLITE_R
24f20 4f 57 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OW] is returned 
24f30 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
24f40 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
24f50 65 61 64 79 0a 2a 2a 20 66 6f 72 20 70 72 6f 63  eady.** for proc
24f60 65 73 73 69 6e 67 20 62 79 20 74 68 65 20 63 61  essing by the ca
24f70 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
24f80 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
24f90 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
24fa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
24fb0 74 20 7c 20 63 6f 6c 75 6d 6e 20 61 63 63 65 73  t | column acces
24fc0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
24fd0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
24fe0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
24ff0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
25000 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
25010 2e 0a 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  ..** .** [SQLITE
25020 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
25030 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
25040 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
25050 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
25060 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
25070 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
25080 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
25090 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
250a0 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
250b0 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
250c0 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
250d0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
250e0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57  _errmsg()]..** W
250f0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
25100 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
25110 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
25120 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a 0a 2a  code (example:.*
25130 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
25140 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
25150 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
25160 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
25170 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
25180 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
25190 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
251a0 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
251b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
251c0 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22  ment].  In the "
251d0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
251e0 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
251f0 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
25200 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
25210 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
25220 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
25230 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
25240 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
25250 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
25260 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
25270 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
25280 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
25290 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
252a0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
252b0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
252c0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
252d0 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
252e0 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
252f0 61 64 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ad .** previousl
25300 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
25310 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
25320 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
25330 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
25340 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
25350 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
25360 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
25370 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
25380 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
25390 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
253a0 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
253b0 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
253c0 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
253d0 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61  >.** In the lega
253e0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 0a 2a  cy interface, .*
253f0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  * the sqlite3_st
25400 65 70 28 29 20 41 50 49 20 61 6c 77 61 79 73 20  ep() API always 
25410 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
25420 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a 2a 2a  c error code,.**
25430 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
25440 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 65   following any e
25450 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
25460 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
25470 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
25480 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
25490 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 72 65  call [sqlite3_re
254a0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
254b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
254c0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
254d0 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 73 70  nd one of the sp
254e0 65 63 69 66 69 63 0a 2a 2a 20 5b 65 72 72 6f 72  ecific.** [error
254f0 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
25500 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
25510 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
25520 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
25530 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
25540 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
25550 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
25560 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
25570 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
25580 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
25590 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
255a0 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
255b0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
255c0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
255d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
255e0 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
255f0 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
25600 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25610 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
25620 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
25630 74 68 65 6e 20 74 68 65 20 0a 2a 2a 20 6d 6f 72  then the .** mor
25640 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
25650 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
25660 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
25670 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
25680 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
25690 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
256a0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
256b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
256c0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
256d0 32 30 32 7d 20 20 49 66 20 5b 70 72 65 70 61 72  202}  If [prepar
256e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
256f0 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 0a 2a  is ready to be.*
25700 2a 20 20 20 20 20 20 20 20 20 20 20 72 75 6e 2c  *           run,
25710 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   then [sqlite3_s
25720 74 65 70 28 53 29 5d 20 61 64 76 61 6e 63 65 73  tep(S)] advances
25730 20 74 68 61 74 20 70 72 65 70 61 72 65 64 20 73   that prepared s
25740 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20  tatement.**     
25750 20 20 20 20 20 20 75 6e 74 69 6c 20 74 6f 20 63        until to c
25760 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74  ompletion or unt
25770 69 6c 20 69 74 20 69 73 20 72 65 61 64 79 20 74  il it is ready t
25780 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72  o return another
25790 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 6f  .**           ro
257a0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
257b0 73 65 74 20 6f 72 20 61 6e 20 69 6e 74 65 72 72  set or an interr
257c0 75 70 74 20 6f 72 20 72 75 6e 2d 74 69 6d 65 20  upt or run-time 
257d0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
257e0 0a 2a 2a 20 7b 46 31 35 33 30 34 7d 20 20 57 68  .** {F15304}  Wh
257f0 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  en a call to [sq
25800 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63  lite3_step(S)] c
25810 61 75 73 65 73 20 74 68 65 20 0a 2a 2a 20 20 20  auses the .**   
25820 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
25830 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74  d statement] S t
25840 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  o run to complet
25850 69 6f 6e 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ion,.**         
25860 20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72    the function r
25870 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
25880 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ONE]..**.** {F15
25890 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63 61 6c  306}  When a cal
258a0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
258b0 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62 65 63  ep(S)] stops bec
258c0 61 75 73 65 20 69 74 20 69 73 20 72 65 61 64 79  ause it is ready
258d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f  .**           to
258e0 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20   return another 
258f0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
25900 74 20 73 65 74 2c 20 69 74 20 72 65 74 75 72 6e  t set, it return
25910 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  s.**           [
25920 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a  SQLITE_ROW]..**.
25930 2a 2a 20 7b 46 31 35 33 30 38 7d 20 20 49 66 20  ** {F15308}  If 
25940 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
25950 65 33 5f 73 74 65 70 28 53 29 5d 20 65 6e 63 6f  e3_step(S)] enco
25960 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20  unters an.**    
25970 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
25980 69 6e 74 65 72 72 75 70 74 7c 69 6e 74 65 72 72  interrupt|interr
25990 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69  upt] or a run-ti
259a0 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20  me error,.**    
259b0 20 20 20 20 20 20 20 69 74 20 72 65 74 75 72 6e         it return
259c0 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
259d0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 68 61 74   error code that
259e0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a   is not one of.*
259f0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
25a00 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45  ITE_OK], [SQLITE
25a10 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  _ROW], or [SQLIT
25a20 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_DONE]..**.** {
25a30 46 31 35 33 31 30 7d 20 20 49 66 20 61 6e 20 5b  F15310}  If an [
25a40 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
25a50 74 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20  t|interrupt] or 
25a60 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a  run-time error.*
25a70 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75  *           occu
25a80 72 73 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c  rs during a call
25a90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
25aa0 70 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  p(S)].**        
25ab0 20 20 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72     for a [prepar
25ac0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
25ad0 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
25ae0 20 20 20 20 20 20 20 20 20 20 20 6c 65 67 61 63             legac
25af0 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  y interfaces [sq
25b00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
25b10 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
25b20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25b30 65 31 36 28 29 5d 20 74 68 65 6e 20 74 68 65 20  e16()] then the 
25b40 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
25b50 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
25b60 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
25b70 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  OR], [SQLITE_BUS
25b80 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  Y], or [SQLITE_M
25b90 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ISUSE]..*/.int s
25ba0 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
25bb0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
25bc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
25bd0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
25be0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b  n a result set {
25bf0 46 31 33 37 37 30 7d 0a 2a 2a 0a 2a 2a 20 52 65  F13770}.**.** Re
25c00 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
25c10 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65  of values in the
25c20 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
25c30 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a  the result set..
25c40 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
25c50 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 31 7d  :.**.** {F13771}
25c60 20 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74    After a call t
25c70 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
25c80 53 29 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73  S)] that returns
25c90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
25ca0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
25cb0 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
25cc0 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 0a  unt(S)] routine.
25cd0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 77 69 6c  **           wil
25ce0 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  l return the sam
25cf0 65 20 76 61 6c 75 65 20 61 73 20 74 68 65 0a 2a  e value as the.*
25d00 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
25d10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
25d20 74 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a  t(S)] function..
25d30 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 32 7d 20 20  **.** {F13772}  
25d40 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  After [sqlite3_s
25d50 74 65 70 28 53 29 5d 20 68 61 73 20 72 65 74 75  tep(S)] has retu
25d60 72 6e 65 64 20 61 6e 79 20 76 61 6c 75 65 20 6f  rned any value o
25d70 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
25d80 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52         [SQLITE_R
25d90 4f 57 5d 20 6f 72 20 62 65 66 6f 72 65 20 5b 73  OW] or before [s
25da0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
25db0 68 61 73 20 62 65 65 6e 20 0a 2a 2a 20 20 20 20  has been .**    
25dc0 20 20 20 20 20 20 20 63 61 6c 6c 65 64 20 6f 6e         called on
25dd0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
25de0 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72 0a 2a 2a  tatement] for.**
25df0 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66             the f
25e00 69 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20  irst time since 
25e10 69 74 20 77 61 73 20 5b 73 71 6c 69 74 65 33 5f  it was [sqlite3_
25e20 70 72 65 70 61 72 65 7c 70 72 65 70 61 72 65 64  prepare|prepared
25e30 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  ].**           o
25e40 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
25e50 7c 72 65 73 65 74 5d 2c 20 74 68 65 20 5b 73 71  |reset], the [sq
25e60 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
25e70 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (S)].**         
25e80 20 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e    routine return
25e90 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73  s zero..*/.int s
25ea0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
25eb0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
25ec0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
25ed0 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
25ee0 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b  ntal Datatypes {
25ef0 46 31 30 32 36 35 7d 0a 2a 2a 20 4b 45 59 57 4f  F10265}.** KEYWO
25f00 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
25f10 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 36 36 7d 45  .**.** {F10266}E
25f20 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
25f30 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
25f40 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
25f50 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
25f60 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
25f70 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
25f80 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
25f90 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
25fa0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
25fb0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
25fc0 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
25fd0 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
25fe0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
25ff0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
26000 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
26010 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
26020 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
26030 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
26040 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
26050 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
26060 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
26070 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
26080 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
26090 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
260a0 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
260b0 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
260c0 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
260d0 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
260e0 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
260f0 54 45 58 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  TEXT not.** SQLI
26100 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
26110 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
26120 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
26130 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
26140 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
26150 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
26160 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
26170 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
26180 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
26190 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
261a0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
261b0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
261c0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
261d0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
261e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
261f0 65 73 75 6c 74 73 20 56 61 6c 75 65 73 20 46 72  esults Values Fr
26200 6f 6d 20 41 20 51 75 65 72 79 20 7b 46 31 33 38  om A Query {F138
26210 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00}.**.** These 
26220 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
26230 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75  e "result set qu
26240 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  ery" interface..
26250 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
26260 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
26270 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a  rmation about.**
26280 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
26290 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
262a0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
262b0 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79  query.  In every
262c0 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 66 69 72  .** case the fir
262d0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
262e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
262f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
26300 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
26310 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c 75 61   being.** evalua
26320 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
26330 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20 77 61  3_stmt*] that wa
26340 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
26350 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
26360 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
26370 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
26380 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20 73 65  s) and.** the se
26390 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
263a0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
263b0 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
263c0 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a  ch information .
263d0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
263e0 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74  urned.  The left
263f0 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  -most column of 
26400 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  the result set.*
26410 2a 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  * has an index o
26420 66 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  f 0..**.** If th
26430 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
26440 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
26450 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
26460 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
26470 0a 2a 2a 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69  .** the column i
26480 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
26490 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
264a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 0a   is undefined. .
264b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
264c0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
264d0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
264e0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
264f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
26500 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
26510 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
26520 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
26530 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
26540 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
26550 6e 61 6c 69 7a 65 28 29 5d 20 68 61 73 20 62 65  nalize()] has be
26560 65 6e 20 63 61 6c 6c 20 73 75 62 73 65 71 75 65  en call subseque
26570 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
26580 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
26590 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
265a0 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
265b0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
265c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
265d0 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
265e0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
265f0 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
26600 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
26610 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
26620 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
26630 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
26640 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
26650 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
26660 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
26670 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
26680 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
26690 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
266a0 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
266b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
266c0 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
266d0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
266e0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 0a  re undefined.  .
266f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
26700 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
26710 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
26720 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
26730 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
26740 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
26750 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
26760 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
26770 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74  column.  The ret
26780 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
26790 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
267a0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
267b0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
267c0 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
267d0 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
267e0 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
267f0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
26800 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
26810 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
26820 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
26830 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
26840 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
26850 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
26860 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
26870 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
26880 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
26890 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
268a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
268b0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
268c0 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
268d0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
268e0 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
268f0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
26900 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
26910 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
26920 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
26930 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  **.** If the res
26940 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
26950 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
26960 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
26970 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 0a 2a  olumn_bytes() .*
26980 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
26990 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
269a0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
269b0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
269c0 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
269d0 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
269e0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
269f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
26a00 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
26a10 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
26a20 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
26a30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
26a40 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72  tes..** If the r
26a50 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
26a60 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
26a70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
26a80 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
26a90 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
26aa0 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
26ab0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
26ac0 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
26ad0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
26ae0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
26af0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
26b00 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
26b10 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
26b20 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
26b30 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65  minator at the e
26b40 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
26b50 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74  ing.  For clarit
26b60 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  y: the value ret
26b70 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d  urned is the num
26b80 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
26b90 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
26ba0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
26bb0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
26bc0 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72  ** Strings retur
26bd0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
26be0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
26bf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26c00 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
26c10 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
26c20 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
26c30 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68   terminated.  Th
26c40 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
26c50 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
26c60 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
26c70 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62   a zero-length b
26c80 6c 6f 62 20 69 73 20 61 6e 20 61 72 62 69 74 72  lob is an arbitr
26c90 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20  ary.** pointer, 
26ca0 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20  possibly even a 
26cb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
26cc0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
26cd0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
26ce0 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
26cf0 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lar to sqlite3_c
26d00 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
26d10 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20   but leaves the 
26d20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36  result in UTF-16
26d30 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
26d40 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
26d50 20 55 54 46 2d 38 2e 20 20 0a 2a 2a 20 54 68 65   UTF-8.  .** The
26d60 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
26d70 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64   is not included
26d80 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a   in this count..
26d90 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74  **.** The object
26da0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
26db0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
26dc0 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
26dd0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
26de0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
26df0 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
26e00 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
26e10 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
26e20 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
26e30 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
26e40 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
26e50 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
26e60 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
26e70 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
26e80 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
26e90 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
26ea0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
26eb0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
26ec0 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
26ed0 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
26ee0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
26ef0 6e 65 73 20 6c 69 6b 65 20 0a 2a 2a 20 5b 73 71  nes like .** [sq
26f00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
26f10 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
26f20 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 20 5b  ue_text()], or [
26f30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
26f40 74 65 73 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  tes()],.** then 
26f50 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
26f60 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
26f70 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
26f80 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
26f90 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
26fa0 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
26fb0 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
26fc0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
26fd0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
26fe0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
26ff0 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
27000 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
27010 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
27020 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
27030 6c 6c 79 20 74 6f 20 64 6f 20 74 68 65 20 63 6f  lly to do the co
27040 6e 76 65 72 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f  nversion.** auto
27050 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
27060 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
27070 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
27080 65 72 73 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  ersions that.** 
27090 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
270a0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
270b0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
270c0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
270d0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
270e0 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
270f0 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
27100 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
27110 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
27120 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
27130 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
27140 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
27150 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
27160 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
27170 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
27180 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
27190 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
271a0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
271b0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
271c0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
271d0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
271e0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
271f0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
27200 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
27210 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
27220 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
27230 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
27240 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
27250 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
27260 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
27270 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
27280 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
27290 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
272a0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
272b0 3e 20 53 61 6d 65 20 61 73 20 66 6f 72 20 49 4e  > Same as for IN
272c0 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
272d0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
272e0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
272f0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
27300 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
27310 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
27320 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
27330 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
27340 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
27350 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
27360 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
27370 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
27380 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
27390 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
273a0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
273b0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
273c0 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
273d0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
273e0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
273f0 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
27400 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
27410 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
27420 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
27430 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
27440 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
27450 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
27460 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
27470 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
27480 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
27490 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
274a0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
274b0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
274c0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
274d0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
274e0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
274f0 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
27500 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
27510 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
27520 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
27530 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
27540 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
27550 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
27560 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
27570 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
27580 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
27590 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
275a0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
275b0 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
275c0 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
275d0 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
275e0 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
275f0 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
27600 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
27610 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
27620 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
27630 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
27640 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
27650 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
27660 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
27670 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
27680 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
27690 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
276a0 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
276b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
276c0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
276d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
276e0 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
276f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
27700 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
27710 74 65 64 2e 20 0a 2a 2a 20 54 79 70 65 20 63 6f  ted. .** Type co
27720 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
27730 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
27740 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
27750 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
27760 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
27770 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e   <ul>.** <li><p>
27780 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f    The initial co
27790 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
277a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
277b0 6d 6e 5f 74 65 78 74 28 29 20 0a 2a 2a 20 20 20  mn_text() .**   
277c0 20 20 20 20 20 20 20 6f 72 20 73 71 6c 69 74 65         or sqlite
277d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
277e0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
277f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
27800 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 20 20  might.**        
27810 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
27820 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
27830 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  .</p></li>.**.**
27840 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e   <li><p>  The in
27850 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
27860 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
27870 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27880 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
27890 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
278a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
278b0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
278c0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
278d0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
278e0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
278f0 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  </p></li>.**.** 
27900 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69  <li><p>  The ini
27910 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
27920 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
27930 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27940 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
27950 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
27960 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
27970 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
27980 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
27990 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  erted.**        
279a0 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c    to UTF-8.</p><
279b0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
279c0 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20  .** Conversions 
279d0 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
279e0 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
279f0 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
27a00 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
27a10 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
27a20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
27a30 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
27a40 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
27a50 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
27a60 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
27a70 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20  inter points to 
27a80 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
27a90 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
27aa0 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
27ab0 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
27ac0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
27ad0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
27ae0 74 20 73 6f 6d 65 74 69 6d 65 20 69 74 20 69 73  t sometime it is
27af0 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  .** not possible
27b00 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
27b10 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
27b20 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
27b30 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ed.  .**.** The 
27b40 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
27b50 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
27b60 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
27b70 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
27b80 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
27b90 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
27ba0 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a  s:.**.**  <ul>.*
27bb0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
27bc0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
27bd0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
27be0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
27bf0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
27c00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
27c10 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
27c20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27c30 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
27c40 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
27c50 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
27c60 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
27c70 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
27c80 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a  /li>.**  </ul>.*
27c90 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
27ca0 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
27cb0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
27cc0 75 6d 6e 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  umn_text(), sqli
27cd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
27ce0 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ),.** or sqlite3
27cf0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
27d00 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
27d10 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
27d20 74 68 65 20 64 65 73 69 72 65 64 0a 2a 2a 20 66  the desired.** f
27d30 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
27d40 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
27d50 6e 5f 62 79 74 65 73 28 29 20 6f 72 20 73 71 6c  n_bytes() or sql
27d60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
27d70 73 31 36 28 29 20 74 6f 0a 2a 2a 20 66 69 6e 64  s16() to.** find
27d80 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
27d90 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
27da0 20 6d 69 78 20 63 61 6c 6c 20 74 6f 20 73 71 6c   mix call to sql
27db0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
27dc0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
27dd0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
27de0 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
27df0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
27e00 73 31 36 28 29 2e 20 20 41 6e 64 20 64 6f 20 6e  s16().  And do n
27e10 6f 74 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c 73 20  ot.** mix calls 
27e20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
27e30 6e 5f 74 65 78 74 31 36 28 29 20 77 69 74 68 20  n_text16() with 
27e40 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
27e50 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
27e60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
27e70 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
27e80 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
27e90 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
27ea0 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
27eb0 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
27ec0 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
27ed0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
27ee0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
27ef0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
27f00 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
27f10 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70  .  The memory sp
27f20 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
27f30 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
27f40 62 6c 6f 62 73 20 69 73 20 66 72 65 65 64 20 61  blobs is freed a
27f50 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
27f60 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
27f70 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
27f80 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
27f90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
27fa0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
27fb0 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
27fc0 2e 20 69 6e 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69  . into .** [sqli
27fd0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
27fe0 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61  ** If a memory a
27ff0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
28000 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
28010 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
28020 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
28030 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
28040 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
28050 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
28060 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
28070 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
28080 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
28090 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
280a0 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
280b0 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
280c0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
280d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
280e0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
280f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
28100 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
28110 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38  NTS:.**.** {F138
28120 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  03} The [sqlite3
28130 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e  _column_blob(S,N
28140 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
28150 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
28160 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
28170 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
28180 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
28190 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
281a0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
281b0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
281c0 6f 20 61 20 62 6c 6f 62 20 61 6e 64 20 74 68 65  o a blob and the
281d0 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20  n returns a.**  
281e0 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20          pointer 
281f0 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64  to the converted
28200 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46   value..**.** {F
28210 31 33 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  13806} The [sqli
28220 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28230 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
28240 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
28250 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
28260 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
28270 62 6c 6f 62 20 6f 72 20 73 74 72 69 6e 67 20 28  blob or string (
28280 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
28290 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
282a0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20  o terminator on 
282b0 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74  the string) that
282c0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79   was returned by
282d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
282e0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
282f0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
28300 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20  lumn_blob(S,N)] 
28310 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
28320 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28330 65 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  ext(S,N)]..**.**
28340 20 7b 46 31 33 38 30 39 7d 20 54 68 65 20 5b 73   {F13809} The [s
28350 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28360 74 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65  tes16(S,N)] inte
28370 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
28380 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
28390 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
283a0 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63   the string (exc
283b0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
283c0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
283d0 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
283e0 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
283f0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
28400 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
28410 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
28420 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
28430 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a  n_text16(S,N)]..
28440 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 32 7d 20 54  **.** {F13812} T
28450 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
28460 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20  mn_double(S,N)] 
28470 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
28480 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
28490 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
284a0 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
284b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
284c0 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
284d0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
284e0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
284f0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
28500 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20  value and.**    
28510 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
28520 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c  copy of that val
28530 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31  ue..**.** {F1381
28540 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
28550 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d  column_int(S,N)]
28560 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
28570 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
28580 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
28590 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
285a0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
285b0 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
285c0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
285d0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
285e0 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
285f0 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
28600 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
28610 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74  the lower 32 bit
28620 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65  s of that intege
28630 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 38  r..**.** {F13818
28640 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
28650 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29  olumn_int64(S,N)
28660 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
28670 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
28680 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
28690 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
286a0 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
286b0 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
286c0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
286d0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
286e0 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
286f0 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20   integer and.** 
28700 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
28710 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
28720 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
28730 46 31 33 38 32 31 7d 20 54 68 65 20 5b 73 71 6c  F13821} The [sql
28740 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
28750 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
28760 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
28770 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
28780 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
28790 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
287a0 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
287b0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
287c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
287d0 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
287e0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 0a 2a  minated UTF-8 .*
287f0 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
28800 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
28810 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
28820 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46  string..**.** {F
28830 31 33 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  13824} The [sqli
28840 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
28850 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
28860 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
28870 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
28880 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
28890 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
288a0 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
288b0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
288c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
288d0 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  S into a zero-te
288e0 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
288f0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
28900 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ned UTF-16 nativ
28910 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
28920 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
28930 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
28940 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
28950 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ring..**.** {F13
28960 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  827} The [sqlite
28970 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c  3_column_type(S,
28980 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
28990 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
289a0 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45    one of [SQLITE
289b0 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NULL], [SQLITE_
289c0 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54  INTEGER], [SQLIT
289d0 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20  E_FLOAT],.**    
289e0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45        [SQLITE_TE
289f0 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  XT], or [SQLITE_
28a00 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72  BLOB] as appropr
28a10 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  iate for.**     
28a20 20 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c       the Nth col
28a30 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
28a40 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
28a50 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
28a60 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
28a70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
28a80 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 33 30 7d 20  .**.** {F13830} 
28a90 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
28aa0 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20  umn_value(S,N)] 
28ab0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28ac0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
28ad0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75  pointer to an [u
28ae0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
28af0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
28b00 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
28b10 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
28b20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
28b30 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
28b40 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
28b50 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
28b60 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
28b70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
28b80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
28b90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28ba0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
28bb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
28bc0 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
28bd0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
28be0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28bf0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
28c00 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
28c10 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
28c20 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
28c30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28c40 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
28c50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
28c60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28c70 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
28c80 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
28c90 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
28ca0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
28cb0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  iCol);.const uns
28cc0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
28cd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
28ce0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28cf0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
28d00 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
28d10 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
28d20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
28d30 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
28d40 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
28d50 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28d60 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
28d70 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
28d80 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
28d90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
28da0 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
28db0 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
28dc0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
28dd0 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 33  ent Object {F133
28de0 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00}.**.** The sq
28df0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
28e00 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
28e10 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
28e20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
28e30 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65  atement]. If the
28e40 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
28e50 2a 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65  * executed succe
28e60 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20  ssfully, or not 
28e70 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c  executed at all,
28e80 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20   then SQLITE_OK 
28e90 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
28ea0 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  If execution of 
28eb0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61  the statement fa
28ec0 69 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a  iled then an .**
28ed0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
28ee0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
28ef0 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74   code].** is ret
28f00 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68  urned. .**.** Th
28f10 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
28f20 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
28f30 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65  point during the
28f40 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
28f50 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
28f60 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74  tatement].  If t
28f70 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69  he virtual machi
28f80 6e 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63  ne has not .** c
28f90 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
28fa0 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75  on when this rou
28fb0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20  tine is called, 
28fc0 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20  that is like.** 
28fd0 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20  encountering an 
28fe0 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65  error or an inte
28ff0 72 72 75 70 74 2e 20 20 28 53 65 65 20 5b 73 71  rrupt.  (See [sq
29000 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
29010 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c  )].) .** Incompl
29020 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20  ete updates may 
29030 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
29040 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  nd transactions 
29050 63 61 6e 63 65 6c 65 64 2c 20 20 0a 2a 2a 20 64  canceled,  .** d
29060 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
29070 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61  circumstances, a
29080 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 65 72 72 6f  nd the .** [erro
29090 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64  r code] returned
290a0 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45   will be [SQLITE
290b0 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _ABORT]..**.** I
290c0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
290d0 20 7b 46 31 31 33 30 32 7d 20 54 68 65 20 5b 73   {F11302} The [s
290e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
290f0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65  S)] interface de
29100 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20  stroys the.**   
29110 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
29120 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e   statement] S an
29130 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a  d releases all.*
29140 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72  *          memor
29150 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75  y and file resou
29160 72 63 65 73 20 68 65 6c 64 20 62 79 20 74 68 61  rces held by tha
29170 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  t object..**.** 
29180 7b 46 31 31 33 30 34 7d 20 49 66 20 74 68 65 20  {F11304} If the 
29190 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
291a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
291b0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
291c0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
291d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
291e0 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72   returned an err
291f0 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  or,.**          
29200 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  then [sqlite3_fi
29210 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72  nalize(S)] retur
29220 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65 72 72  ns that same err
29230 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  or..*/.int sqlit
29240 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
29250 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
29260 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29270 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
29280 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
29290 6a 65 63 74 20 7b 46 31 33 33 33 30 7d 0a 2a 2a  ject {F13330}.**
292a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
292b0 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
292c0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
292d0 73 65 74 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61  set a .** [prepa
292e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
292f0 62 6a 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20 74  bject..** back t
29300 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
29310 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
29320 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
29330 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   Any SQL stateme
29340 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
29350 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
29360 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
29370 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
29380 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
29390 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
293a0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
293b0 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
293c0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
293d0 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
293e0 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
293f0 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 32 7d 20  .**.** {F11332} 
29400 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
29410 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
29420 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
29430 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29440 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62   S.**          b
29450 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
29460 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
29470 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33  ram..**.** {F113
29480 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  34} 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 20 0a 2a 2a 20 20 20 20 20 20 20 20   for .**        
294c0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
294d0 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
294e0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
294f0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
29500 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
29510 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
29520 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
29530 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
29540 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20  d on S,.**      
29550 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
29560 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
29570 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
29580 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 36 7d 20  .**.** {F11336} 
29590 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
295a0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
295b0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
295c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
295d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
295e0 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
295f0 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
29600 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
29610 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
29620 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
29630 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
29640 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 38 7d 20  .**.** {F11338} 
29650 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
29660 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
29670 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
29680 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20   the values.**  
29690 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b          of any [
296a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
296b0 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 5b  b|bindings] on [
296c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
296d0 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
296e0 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
296f0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
29700 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29710 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
29720 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
29730 6f 6e 73 20 7b 46 31 36 31 30 30 7d 0a 2a 2a 20  ons {F16100}.** 
29740 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
29750 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
29760 74 69 6e 65 73 7d 20 0a 2a 2a 0a 2a 2a 20 54 68  tines} .**.** Th
29770 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ese two function
29780 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
29790 6b 6e 6f 77 6e 20 61 73 0a 2a 2a 20 22 66 75 6e  known as.** "fun
297a0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
297b0 6f 75 74 69 6e 65 73 22 29 20 61 72 65 20 75 73  outines") are us
297c0 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
297d0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
297e0 67 61 74 65 73 0a 2a 2a 20 6f 72 20 74 6f 20 72  gates.** or to r
297f0 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
29800 76 69 6f 72 20 6f 66 20 65 78 69 73 74 69 6e 67  vior of existing
29810 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
29820 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
29830 68 65 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63 65  he.** difference
29840 20 6f 6e 6c 79 20 62 65 74 77 65 65 6e 20 74 68   only between th
29850 65 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68  e two is that th
29860 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
29870 65 72 2c 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20  er, the.** name 
29880 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 20  of the (scalar) 
29890 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
298a0 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65  egate, is encode
298b0 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d in UTF-8 for.*
298c0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
298d0 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20  _function() and 
298e0 55 54 46 2d 31 36 20 66 6f 72 20 73 71 6c 69 74  UTF-16 for sqlit
298f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
29900 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  on16()..**.** Th
29910 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
29920 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
29930 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
29940 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
29950 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
29960 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20  o be added.  If 
29970 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f 67  a single.** prog
29980 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ram uses more th
29990 61 6e 20 6f 6e 65 20 5b 64 61 74 61 62 61 73 65  an one [database
299a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74   connection] int
299b0 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51  ernally, then SQ
299c0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6d  L.** functions m
299d0 75 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64  ust be added ind
299e0 69 76 69 64 75 61 6c 6c 79 20 74 6f 20 65 61 63  ividually to eac
299f0 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  h [database conn
29a00 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54  ection]..**.** T
29a10 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
29a20 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
29a30 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
29a40 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
29a50 64 0a 2a 2a 20 6f 72 20 72 65 64 65 66 69 6e 65  d.** or redefine
29a60 64 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e 67 74 68  d..** The length
29a70 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
29a80 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
29a90 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20  ytes, exclusive 
29aa0 6f 66 20 74 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d  of the .** zero-
29ab0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74  terminator.  Not
29ac0 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20  e that the name 
29ad0 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
29ae0 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a  in bytes, not.**
29af0 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e   characters.  An
29b00 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
29b10 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
29b20 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
29b30 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
29b40 20 69 6e 20 61 6e 20 53 51 4c 49 54 45 5f 45 52   in an SQLITE_ER
29b50 52 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a  ROR error..**.**
29b60 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
29b70 65 74 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62  eter is the numb
29b80 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
29b90 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
29ba0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
29bb0 65 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20  egate takes. If 
29bc0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
29bd0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
29be0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
29bf0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
29c00 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
29c10 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
29c20 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ts..**.** The fo
29c30 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
29c40 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
29c50 69 65 73 20 77 68 61 74 20 0a 2a 2a 20 5b 53 51  ies what .** [SQ
29c60 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
29c70 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
29c80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
29c90 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
29ca0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79  parameters.  Any
29cb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
29cc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
29cd0 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77  uld be able to w
29ce0 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68  ork.** work with
29cf0 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65   UTF-8, UTF-16le
29d00 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20  , or UTF-16be.  
29d10 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65  But some impleme
29d20 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a  ntations may be.
29d30 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e  ** more efficien
29d40 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64  t with one encod
29d50 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72  ing than another
29d60 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64  .  It is allowed
29d70 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
29d80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
29d90 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ction() or sqlit
29da0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
29db0 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a  on16() multiple.
29dc0 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  ** times with th
29dd0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
29de0 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
29df0 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65  nt values of eTe
29e00 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d  xtRep..** When m
29e10 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
29e20 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
29e30 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
29e40 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
29e50 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
29e60 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
29e70 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
29e80 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
29e90 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66  onversion..** If
29ea0 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61   there is only a
29eb0 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e   single implemen
29ec0 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65  tation which doe
29ed0 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 0a  s not care what.
29ee0 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
29ef0 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74   is used, then t
29f00 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
29f10 6e 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  nt should be.** 
29f20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
29f30 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61  .** The fifth pa
29f40 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
29f50 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
29f60 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
29f70 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 66  tion.** of the f
29f80 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
29f90 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
29fa0 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 0a 2a 2a  pointer using.**
29fb0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
29fc0 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  ata()]..**.** Th
29fd0 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74  e seventh, eight
29fe0 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61  h and ninth para
29ff0 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
2a000 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
2a010 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
2a020 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
2a030 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
2a040 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 0a  plement the SQL.
2a050 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  ** function or a
2a060 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c  ggregate. A scal
2a070 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
2a080 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2a090 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ementation of.**
2a0a0 20 74 68 65 20 78 46 75 6e 63 20 63 61 6c 6c 62   the xFunc callb
2a0b0 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70  ack only, NULL p
2a0c0 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62  ointers should b
2a0d0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2a0e0 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
2a0f0 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 2e 20  nal parameters. 
2a100 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
2a110 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2a120 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2a130 74 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74 65 70  tion.** of xStep
2a140 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
2a150 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70  NULL should be p
2a160 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
2a170 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a   To delete an.**
2a180 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
2a190 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2a1a0 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66  ate, pass NULL f
2a1b0 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
2a1c0 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
2a1d0 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ks..**.** It is 
2a1e0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
2a1f0 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
2a200 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2a210 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
2a220 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
2a230 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
2a240 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
2a250 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
2a260 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
2a270 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
2a280 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
2a290 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  gs.  SQLite will
2a2a0 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
2a2b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20  ementation most 
2a2c0 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
2a2d0 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
2a2e0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
2a2f0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
2a300 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2a310 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 33 7d 20 54  **.** {F16103} T
2a320 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2a330 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2a340 20 69 6e 74 65 72 66 61 63 65 20 62 65 68 61 76   interface behav
2a350 65 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20  es exactly.**   
2a360 20 20 20 20 20 20 20 6c 69 6b 65 20 5b 73 71 6c         like [sql
2a370 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2a380 74 69 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72 79  tion()] in every
2a390 20 77 61 79 20 65 78 63 65 70 74 20 74 68 61 74   way except that
2a3a0 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   it.**          
2a3b0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 7a  interprets the z
2a3c0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72 67  FunctionName arg
2a3d0 75 6d 65 6e 74 20 61 73 0a 2a 2a 20 20 20 20 20  ument as.**     
2a3e0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
2a3f0 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69  ated UTF-16 nati
2a400 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e  ve byte order in
2a410 73 74 65 61 64 20 6f 66 20 61 73 20 61 0a 2a 2a  stead of as a.**
2a420 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
2a430 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 2e  erminated UTF-8.
2a440 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 36 7d 20  .**.** {F16106} 
2a450 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
2a460 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20  ocation of.**   
2a470 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
2a480 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2a490 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29  ion(D,X,N,E,...)
2a4a0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
2a4b0 73 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  sters.**        
2a4c0 20 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63 61    or replaces ca
2a4d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
2a4e0 20 69 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   in [database co
2a4f0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20  nnection] D.**  
2a500 20 20 20 20 20 20 20 20 75 73 65 64 20 74 6f 20          used to 
2a510 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2a520 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64  L function named
2a530 20 58 20 77 69 74 68 20 4e 20 70 61 72 61 6d 65   X with N parame
2a540 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
2a550 20 61 6e 64 20 68 61 76 69 6e 67 20 61 20 70 72   and having a pr
2a560 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2a570 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a  oding of E..**.*
2a580 2a 20 7b 46 31 36 31 30 39 7d 20 41 20 73 75 63  * {F16109} A suc
2a590 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2a5a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2a5b0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2a5c0 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20  ,P,F,S,L)].**   
2a5d0 20 20 20 20 20 20 20 72 65 70 6c 61 63 65 73 20         replaces 
2a5e0 74 68 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64  the P, F, S, and
2a5f0 20 4c 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 61   L values from a
2a600 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77  ny prior calls w
2a610 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
2a620 74 68 65 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e  the same D, X, N
2a630 2c 20 61 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a  , and E values..
2a640 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 32 7d 20 54  **.** {F16112} T
2a650 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2a660 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2a670 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
2a680 66 61 69 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20  fails with.**   
2a690 20 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20         a return 
2a6a0 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
2a6b0 45 52 52 4f 52 5d 20 69 66 20 74 68 65 20 53 51  ERROR] if the SQ
2a6c0 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20  L function name 
2a6d0 58 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  X is.**         
2a6e0 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20 32 35 35   longer than 255
2a6f0 20 62 79 74 65 73 20 65 78 63 6c 75 73 69 76 65   bytes exclusive
2a700 20 6f 66 20 74 68 65 20 7a 65 72 6f 20 74 65 72   of the zero ter
2a710 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  minator..**.** {
2a720 46 31 36 31 31 38 7d 20 45 69 74 68 65 72 20 46  F16118} Either F
2a730 20 6d 75 73 74 20 62 65 20 4e 55 4c 4c 20 61 6e   must be NULL an
2a740 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f  d S and L are no
2a750 6e 2d 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 46  n-NULL or else F
2a760 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
2a770 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 61  non-NULL and S a
2a780 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c 2c 20 6f  nd L are NULL, o
2a790 74 68 65 72 77 69 73 65 0a 2a 2a 20 20 20 20 20  therwise.**     
2a7a0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72       [sqlite3_cr
2a7b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2a7c0 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20  X,N,E,P,F,S,L)] 
2a7d0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
2a7e0 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ERROR]..**.** {F
2a7f0 31 36 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  16121} The [sqli
2a800 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2a810 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65  ion(D,...)] inte
2a820 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
2a830 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
2a840 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53  error code of [S
2a850 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20 74  QLITE_BUSY] if t
2a860 68 65 72 65 20 65 78 69 73 74 20 5b 70 72 65 70  here exist [prep
2a870 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2a880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73  .**          ass
2a890 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2a8a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2a8b0 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
2a8c0 7b 46 31 36 31 32 34 7d 20 54 68 65 20 5b 73 71  {F16124} The [sq
2a8d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2a8e0 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29  ction(D,X,N,...)
2a8f0 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  ] interface fail
2a900 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20  s with an.**    
2a910 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65        error code
2a920 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   of [SQLITE_ERRO
2a930 52 5d 20 69 66 20 70 61 72 61 6d 65 74 65 72 20  R] if parameter 
2a940 4e 20 28 73 70 65 63 69 66 79 69 6e 67 20 74 68  N (specifying th
2a950 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20  e number.**     
2a960 20 20 20 20 20 6f 66 20 61 72 67 75 6d 65 6e 74       of argument
2a970 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  s to the SQL fun
2a980 63 74 69 6f 6e 20 62 65 69 6e 67 20 72 65 67 69  ction being regi
2a990 73 74 65 72 65 64 29 20 69 73 20 6c 65 73 73 0a  stered) is less.
2a9a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 6e  **          than
2a9b0 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
2a9c0 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b  han 127..**.** {
2a9d0 46 31 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69  F16127} When N i
2a9e0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
2a9f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2aa00 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2aa10 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,N,...)].**     
2aa20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63       interface c
2aa30 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20  auses callbacks 
2aa40 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f  to be invoked fo
2aa50 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  r the SQL functi
2aa60 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  on.**          n
2aa70 61 6d 65 64 20 58 20 77 68 65 6e 20 74 68 65 20  amed X when the 
2aa80 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2aa90 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66  nts to the SQL f
2aaa0 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20  unction is.**   
2aab0 20 20 20 20 20 20 20 65 78 61 63 74 6c 79 20 4e         exactly N
2aac0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 30 7d  ..**.** {F16130}
2aad0 20 57 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20 74   When N is -1, t
2aae0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2aaf0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2ab00 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  N,...)].**      
2ab10 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61      interface ca
2ab20 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74  uses callbacks t
2ab30 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72  o be invoked for
2ab40 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2ab50 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61  n.**          na
2ab60 6d 65 64 20 58 20 77 69 74 68 20 61 6e 79 20 6e  med X with any n
2ab70 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2ab80 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33  ts..**.** {F1613
2ab90 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f  3} When calls to
2aba0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2abb0 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2abc0 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
2abd0 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70    specify multip
2abe0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2abf0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
2ac00 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20  unction X.**    
2ac10 20 20 20 20 20 20 61 6e 64 20 77 68 65 6e 20 6f        and when o
2ac20 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ne implementatio
2ac30 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74  n has N>=0 and t
2ac40 68 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d 28  he other has N=(
2ac50 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  -1).**          
2ac60 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2ac70 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  on with a non-ze
2ac80 72 6f 20 4e 20 69 73 20 70 72 65 66 65 72 72 65  ro N is preferre
2ac90 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 36  d..**.** {F16136
2aca0 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  } When calls to 
2acb0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2acc0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2acd0 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2ace0 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69     specify multi
2acf0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2ad00 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2ad10 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 0a  function X with.
2ad20 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2ad30 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20 61  same number of a
2ad40 72 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 20 77  rguments N but w
2ad50 69 74 68 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a  ith different.**
2ad60 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 69            encodi
2ad70 6e 67 73 20 45 2c 20 74 68 65 6e 20 74 68 65 20  ngs E, then the 
2ad80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2ad90 68 65 72 65 20 45 20 6d 61 74 63 68 65 73 20 74  here E matches t
2ada0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  he.**          d
2adb0 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
2adc0 20 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a   is preferred..*
2add0 2a 0a 2a 2a 20 7b 46 31 36 31 33 39 7d 20 46 6f  *.** {F16139} Fo
2ade0 72 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 53  r an aggregate S
2adf0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  QL function crea
2ae00 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ted using.**    
2ae10 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
2ae20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2ae30 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d  ,X,N,E,P,0,S,L)]
2ae40 20 74 68 65 20 66 69 6e 69 61 6c 69 7a 65 72 0a   the finializer.
2ae50 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63  **          func
2ae60 74 69 6f 6e 20 4c 20 77 69 6c 6c 20 61 6c 77 61  tion L will alwa
2ae70 79 73 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 78  ys be invoked ex
2ae80 61 63 74 6c 79 20 6f 6e 63 65 20 69 66 20 74 68  actly once if th
2ae90 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  e.**          st
2aea0 65 70 20 66 75 6e 63 74 69 6f 6e 20 53 20 69 73  ep function S is
2aeb0 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
2aec0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a  ore times..**.**
2aed0 20 7b 46 31 36 31 34 32 7d 20 57 68 65 6e 20 53   {F16142} When S
2aee0 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 65 69  QLite invokes ei
2aef0 74 68 65 72 20 74 68 65 20 78 46 75 6e 63 20 6f  ther the xFunc o
2af00 72 20 78 53 74 65 70 20 66 75 6e 63 74 69 6f 6e  r xStep function
2af10 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
2af20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
2af30 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2af40 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2af50 20 63 72 65 61 74 65 64 0a 2a 2a 20 20 20 20 20   created.**     
2af60 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33       by [sqlite3
2af70 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2af80 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2af90 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2afa0 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  6()],.**        
2afb0 20 20 74 68 65 6e 20 74 68 65 20 61 72 72 61 79    then the array
2afc0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
2afd0 75 65 5d 20 6f 62 6a 65 63 74 73 20 70 61 73 73  ue] objects pass
2afe0 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20  ed as the.**    
2aff0 20 20 20 20 20 20 74 68 69 72 64 20 70 61 72 61        third para
2b000 6d 65 74 65 72 20 61 72 65 20 61 6c 77 61 79 73  meter are always
2b010 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2b020 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2b030 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ts..*/.int sqlit
2b040 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2b050 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
2b060 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
2b070 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
2b080 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
2b090 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
2b0a0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
2b0b0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
2b0c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2b0d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2b0e0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
2b0f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2b100 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2b110 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2b120 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
2b130 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
2b140 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2b150 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
2b160 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
2b170 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
2b180 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
2b190 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
2b1a0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
2b1b0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
2b1c0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2b1d0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2b1e0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2b1f0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
2b200 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2b210 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2b220 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
2b230 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2b240 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t*).);../*.** CA
2b250 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
2b260 6f 64 69 6e 67 73 20 7b 46 31 30 32 36 37 7d 0a  odings {F10267}.
2b270 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2b280 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
2b290 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
2b2a0 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
2b2b0 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
2b2c0 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
2b2d0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
2b2e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2b2f0 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
2b300 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2b310 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
2b320 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2b330 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
2b340 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2b350 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
2b360 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
2b370 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
2b380 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
2b390 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
2b3a0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
2b3b0 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
2b3c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2b3d0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
2b3e0 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
2b3f0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2b400 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
2b410 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 73 6f  * CAPI3REF: Obso
2b420 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  lete Functions.*
2b430 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2b440 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77  ions are all now
2b450 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f   obsolete.  In o
2b460 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
2b470 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
2b480 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
2b490 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77 65 20   older code, we 
2b4a0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75 70 70  continue to supp
2b4b0 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e  ort.** these fun
2b4c0 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72  ctions.  However
2b4d0 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e  , new developmen
2b4e0 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c  t projects shoul
2b4f0 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
2b500 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
2b510 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
2b520 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
2b530 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
2b540 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
2b550 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
2b560 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
2b570 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a   want they do..*
2b580 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  /.int sqlite3_ag
2b590 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
2b5a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2b5b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70  .int sqlite3_exp
2b5c0 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
2b5d0 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
2b5e0 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
2b5f0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2b600 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
2b610 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  ;.int sqlite3_gl
2b620 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
2b630 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  d);.void sqlite3
2b640 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
2b650 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
2b660 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
2b670 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
2b680 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
2b690 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  ,void*,sqlite3_i
2b6a0 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
2b6b0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
2b6c0 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
2b6d0 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20  arameter Values 
2b6e0 7b 46 31 35 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F15100}.**.** T
2b6f0 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
2b700 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2b710 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
2b720 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
2b730 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
2b740 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
2b750 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
2b760 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
2b770 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
2b780 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
2b790 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
2b7a0 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
2b7b0 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
2b7c0 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
2b7d0 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
2b7e0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
2b7f0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2b800 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2b810 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2b820 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
2b830 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
2b840 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
2b850 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2b860 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
2b870 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2b880 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
2b890 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
2b8a0 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
2b8b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b8c0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2b8d0 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
2b8e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2b8f0 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
2b900 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
2b910 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2b920 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
2b930 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
2b940 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
2b950 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
2b960 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2b970 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2b980 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
2b990 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
2b9a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2b9b0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
2b9c0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
2b9d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
2b9e0 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
2b9f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
2ba00 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
2ba10 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
2ba20 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  ehavior..**.** T
2ba30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
2ba40 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
2ba50 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 0a   corresponding .
2ba60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2ba70 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  mn_blob | sqlite
2ba80 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74 69  3_column_* routi
2ba90 6e 65 73 5d 20 65 78 63 65 70 74 20 74 68 61 74  nes] except that
2baa0 20 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69   .** these routi
2bab0 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
2bac0 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
2bad0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2bae0 63 74 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 69 6e  ct pointer.** in
2baf0 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
2bb00 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
2bb10 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
2bb20 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
2bb30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2bb40 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2bb50 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
2bb60 61 63 74 73 20 61 20 55 54 46 31 36 20 73 74 72  acts a UTF16 str
2bb70 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
2bb80 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
2bb90 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
2bba0 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ine.  The.** sql
2bbb0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2bbc0 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
2bbd0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2bbe0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
2bbf0 20 65 78 74 72 61 63 74 20 55 54 46 31 36 20 73   extract UTF16 s
2bc00 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
2bc10 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
2bc20 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
2bc30 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
2bc40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
2bc50 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
2bc60 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
2bc70 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
2bc80 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
2bc90 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
2bca0 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
2bcb0 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
2bcc0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
2bcd0 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
2bce0 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
2bcf0 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
2bd00 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
2bd10 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
2bd20 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
2bd30 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
2bd40 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66 20 74 68  r.** words if th
2bd50 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
2bd60 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
2bd70 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
2bd80 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
2bd90 73 69 6f 6e 20 69 73 20 64 6f 6e 65 2e 20 20 4f  sion is done.  O
2bda0 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
2bdb0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20  ersion occurs.  
2bdc0 54 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  The .** [SQLITE_
2bdd0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
2bde0 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
2bdf0 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
2be00 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ..**.** Please p
2be10 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
2be20 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
2be30 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
2be40 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  nter that.** is 
2be50 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
2be60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
2be70 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
2be80 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
2be90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2bea0 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
2beb0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
2bec0 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
2bed0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2bee0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2bef0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2bf00 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
2bf10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2bf20 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2bf30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2bf40 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  16()].  .**.** T
2bf50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
2bf60 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
2bf70 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
2bf80 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
2bf90 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
2bfa0 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
2bfb0 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
2bfc0 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a  meters..**.**.**
2bfd0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2bfe0 2a 2a 20 7b 46 31 35 31 30 33 7d 20 54 68 65 20  ** {F15103} The 
2bff0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2c000 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72 66 61 63  lob(V)] interfac
2c010 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2c020 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2c030 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c040 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2c050 74 6f 20 61 20 62 6c 6f 62 20 61 6e 64 20 74 68  to a blob and th
2c060 65 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20  en returns a.** 
2c070 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72           pointer
2c080 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65   to the converte
2c090 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b  d value..**.** {
2c0a0 46 31 35 31 30 36 7d 20 54 68 65 20 5b 73 71 6c  F15106} The [sql
2c0b0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2c0c0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (V)] interface r
2c0d0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
2c0e0 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
2c0f0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 62 6c   bytes in the bl
2c100 6f 62 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78  ob or string (ex
2c110 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
2c120 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
2c130 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
2c140 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
2c150 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
2c160 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
2c170 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2c180 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  to [sqlite3_valu
2c190 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a  e_blob(V)] or.**
2c1a0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2c1b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29  e3_value_text(V)
2c1c0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 39  ]..**.** {F15109
2c1d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2c1e0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 56 29 5d  alue_bytes16(V)]
2c1f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2c200 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
2c210 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
2c220 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
2c230 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74   (exclusive of t
2c240 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  he.**          z
2c250 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f  ero terminator o
2c260 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68  n the string) th
2c270 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
2c280 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
2c290 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63     most recent c
2c2a0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2c2b0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d  value_text16(V)]
2c2c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
2c2d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2c2e0 74 31 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73  t16be(V)], or [s
2c2f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2c300 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a  t16le(V)]..**.**
2c310 20 7b 46 31 35 31 31 32 7d 20 54 68 65 20 5b 73   {F15112} The [s
2c320 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
2c330 62 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ble(V)] interfac
2c340 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2c350 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2c360 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c370 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2c380 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  to a floating po
2c390 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a  int value and.**
2c3a0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2c3b0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74  s a copy of that
2c3c0 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46   value..**.** {F
2c3d0 31 35 31 31 35 7d 20 54 68 65 20 5b 73 71 6c 69  15115} The [sqli
2c3e0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29  te3_value_int(V)
2c3f0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2c400 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2c410 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2c420 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c430 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36  bject V into a 6
2c440 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2c450 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20  eger and.**     
2c460 20 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65       returns the
2c470 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f   lower 32 bits o
2c480 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a  f that integer..
2c490 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 38 7d 20 54  **.** {F15118} T
2c4a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2c4b0 65 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65  e_int64(V)] inte
2c4c0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2c4d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2c4e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c4f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2c500 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  V into a 64-bit 
2c510 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
2c520 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
2c530 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2c540 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
2c550 2a 0a 2a 2a 20 7b 46 31 35 31 32 31 7d 20 54 68  *.** {F15121} 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 28 56 29 5d 20 69 6e 74 65 72 66  _text(V)] interf
2c580 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2c590 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2c5a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c5b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2c5c0 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2c5d0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 0a 2a 2a  inated UTF-8 .**
2c5e0 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
2c5f0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2c600 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
2c610 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
2c620 35 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  5124} The [sqlit
2c630 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2c640 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2c650 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2c660 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
2c670 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2c680 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
2c690 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2c6a0 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20   2-byte.**      
2c6b0 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d      aligned UTF-
2c6c0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
2c6d0 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rder.**         
2c6e0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2c6f0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2c700 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2c710 0a 2a 2a 20 7b 46 31 35 31 32 37 7d 20 54 68 65  .** {F15127} The
2c720 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c730 74 65 78 74 31 36 62 65 28 56 29 5d 20 69 6e 74  text16be(V)] int
2c740 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2c750 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c760 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2c770 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c780 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
2c790 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
2c7a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69  .**          ali
2c7b0 67 6e 65 64 20 55 54 46 2d 31 36 20 62 69 67 2d  gned UTF-16 big-
2c7c0 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
2c7d0 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
2c7e0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2c7f0 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
2c800 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 30 7d 20 54  **.** {F15130} T
2c810 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2c820 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 20 69  e_text16le(V)] i
2c830 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2c840 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c850 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2c860 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2c870 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
2c880 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
2c890 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
2c8a0 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6c 69  ligned UTF-16 li
2c8b0 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20  ttle-endian.**  
2c8c0 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
2c8d0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2c8e0 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
2c8f0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  ing..**.** {F151
2c900 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  33} The [sqlite3
2c910 5f 76 61 6c 75 65 5f 74 79 70 65 28 56 29 5d 20  _value_type(V)] 
2c920 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2c930 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e  s.**          on
2c940 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  e of [SQLITE_NUL
2c950 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  L], [SQLITE_INTE
2c960 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c  GER], [SQLITE_FL
2c970 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  OAT],.**        
2c980 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c    [SQLITE_TEXT],
2c990 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42   or [SQLITE_BLOB
2c9a0 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65  ] as appropriate
2c9b0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
2c9c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2c9d0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a  lue] object V..*
2c9e0 2a 0a 2a 2a 20 7b 46 31 35 31 33 36 7d 20 54 68  *.** {F15136} Th
2c9f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2ca00 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 56 29  _numeric_type(V)
2ca10 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2ca20 65 72 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  erts.**         
2ca30 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20   the [protected 
2ca40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2ca50 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 65 69 74  bject V into eit
2ca60 68 65 72 20 61 6e 20 69 6e 74 65 67 65 72 20 6f  her an integer o
2ca70 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
2ca80 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
2ca90 61 6c 75 65 20 69 66 20 69 74 20 63 61 6e 20 64  alue if it can d
2caa0 6f 20 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73  o so without los
2cab0 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s of.**         
2cac0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e   information, an
2cad0 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66  d returns one of
2cae0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a   [SQLITE_NULL],.
2caf0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
2cb00 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53  ITE_INTEGER], [S
2cb10 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
2cb20 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a  QLITE_TEXT], or.
2cb30 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
2cb40 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70  ITE_BLOB] as app
2cb50 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20  ropriate for.** 
2cb60 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
2cb70 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2cb80 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2cb90 61 66 74 65 72 20 74 68 65 20 63 6f 6e 76 65 72  after the conver
2cba0 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f  sion attempt..*/
2cbb0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2cbc0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
2cbd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2cbe0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2cbf0 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
2cc00 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2cc10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2cc20 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
2cc30 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  e*);.double sqli
2cc40 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
2cc50 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2cc60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2cc70 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
2cc80 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33  value*);.sqlite3
2cc90 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
2cca0 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
2ccb0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
2ccc0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
2ccd0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2cce0 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
2ccf0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
2cd00 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2cd10 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
2cd20 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
2cd30 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2cd40 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
2cd50 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2cd60 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2cd70 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
2cd80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2cd90 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2cda0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
2cdb0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2cdc0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2cdd0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
2cde0 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
2cdf0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
2ce00 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
2ce10 6e 20 43 6f 6e 74 65 78 74 20 7b 46 31 36 32 31  n Context {F1621
2ce20 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70  0}.**.** The imp
2ce30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
2ce40 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2ce50 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20  ctions use this 
2ce60 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
2ce70 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75  ate.** a structu
2ce80 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  re for storing t
2ce90 68 65 69 72 20 73 74 61 74 65 2e 20 20 0a 2a 2a  heir state.  .**
2cea0 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
2ceb0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
2cec0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2ced0 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 69 73  routine is.** is
2cee0 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 20 70 61   called for a pa
2cef0 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
2cf00 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63  te, SQLite alloc
2cf10 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d  ates nBytes of m
2cf20 65 6d 6f 72 79 0a 2a 2a 20 7a 65 72 6f 73 20 74  emory.** zeros t
2cf30 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
2cf40 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2cf50 72 20 74 6f 20 69 74 2e 0a 2a 2a 20 4f 6e 20 73  r to it..** On s
2cf60 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2cf70 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71  uent calls to sq
2cf80 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2cf90 63 6f 6e 74 65 78 74 28 29 0a 2a 2a 20 66 6f 72  context().** for
2cfa0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
2cfb0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64  ate function ind
2cfc0 65 78 2c 20 74 68 65 20 73 61 6d 65 20 62 75 66  ex, the same buf
2cfd0 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
2cfe0 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
2cff0 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
2d000 20 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75   aggregate can u
2d010 73 65 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  se the returned 
2d020 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75  buffer to accumu
2d030 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  late data..**.**
2d040 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
2d050 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
2d060 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72  allocated buffer
2d070 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
2d080 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e  ate.** query con
2d090 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
2d0a0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2d0b0 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f  r should be a co
2d0c0 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b 73  py of the .** [s
2d0d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
2d0e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
2d0f0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
2d100 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
2d110 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
2d120 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
2d130 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
2d140 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
2d150 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
2d160 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
2d170 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2d180 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2d190 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2d1a0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2d1b0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2d1c0 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  g..**.** INVARIA
2d1d0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  NTS:.**.** {F162
2d1e0 31 31 7d 20 54 68 65 20 66 69 72 73 74 20 69 6e  11} The first in
2d1f0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
2d200 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2d210 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72  ontext(C,N)] for
2d220 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70  .**          a p
2d230 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e  articular instan
2d240 63 65 20 6f 66 20 61 6e 20 61 67 67 72 65 67 61  ce of an aggrega
2d250 74 65 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72  te function (for
2d260 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
2d270 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78            contex
2d280 74 20 43 29 20 63 61 75 73 65 73 20 53 51 4c 69  t C) causes SQLi
2d290 74 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  te to allocation
2d2a0 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f   N bytes of memo
2d2b0 72 79 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ry,.**          
2d2c0 7a 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79  zero that memory
2d2d0 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70  , and return a p
2d2e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 61 6c  ointer to the al
2d2f0 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  located.**      
2d300 20 20 20 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a      memory..**.*
2d310 2a 20 7b 46 31 36 32 31 33 7d 20 49 66 20 61 20  * {F16213} If a 
2d320 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2d330 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
2d340 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  uring.**        
2d350 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65    [sqlite3_aggre
2d360 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
2d370 29 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63  )] then the func
2d380 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a  tion returns 0..
2d390 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 35 7d 20 53  **.** {F16215} S
2d3a0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2d3b0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73  uent invocations
2d3c0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
2d3d0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2d3e0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
2d3f0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f   for the same co
2d400 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a  ntext pointer C.
2d410 2a 2a 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f  **          igno
2d420 72 65 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  re the N paramet
2d430 65 72 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20  er and return a 
2d440 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73  pointer to the s
2d450 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
2d460 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
2d470 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
2d480 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e  first invocation
2d490 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 37 7d  ..**.** {F16217}
2d4a0 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
2d4b0 63 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  cated by [sqlite
2d4c0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2d4d0 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20  ext(C,N)] is.** 
2d4e0 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74           automat
2d4f0 69 63 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20  ically freed on 
2d500 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
2d510 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2d520 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
2d530 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2d540 69 7a 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b  ize()] for the [
2d550 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d560 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a  nt] containing.*
2d570 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
2d580 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2d590 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  n associated wit
2d5a0 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a  h context C..*/.
2d5b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67  void *sqlite3_ag
2d5c0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2d5d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d5e0 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
2d5f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d600 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
2d610 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32 34 30 7d  nctions {F16240}
2d620 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2d630 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
2d640 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2d650 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
2d660 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
2d670 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
2d680 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
2d690 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
2d6a0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
2d6b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2d6c0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
2d6d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d6e0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
2d6f0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
2d700 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
2d710 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2d720 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
2d730 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  n. {END}.**.** T
2d740 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
2d750 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2d760 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2d770 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2d780 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2d790 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
2d7a0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49  running..**.** I
2d7b0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2d7c0 20 7b 46 31 36 32 34 33 7d 20 54 68 65 20 5b 73   {F16243} The [s
2d7d0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2d7e0 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (C)] interface r
2d7f0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2d800 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2d810 20 50 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20   P pointer from 
2d820 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2d830 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2d840 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a  ,N,E,P,F,S,L)].*
2d850 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
2d860 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2d870 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45  nction16(D,X,N,E
2d880 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20  ,P,F,S,L)] call 
2d890 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
2d8a0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
2d8b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73  SQL function ass
2d8c0 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a  ociated with .**
2d8d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2d8e0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a  e3_context] C..*
2d8f0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
2d900 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
2d910 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
2d920 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2d930 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2d940 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20  n For Functions 
2d950 7b 46 31 36 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F16250}.**.** T
2d960 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
2d970 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
2d980 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2d990 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
2d9a0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
2d9b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2d9c0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
2d9d0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
2d9e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2d9f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2da00 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2da10 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2da20 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
2da30 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
2da40 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
2da50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2da60 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
2da70 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2da80 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 35 33 7d 20  .**.** {F16253} 
2da90 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
2daa0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43  text_db_handle(C
2dab0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2dac0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
2dad0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44  he.**          D
2dae0 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68   pointer from th
2daf0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2db00 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2db10 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20  ,E,P,F,S,L)].** 
2db20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
2db30 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2db40 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50  tion16(D,X,N,E,P
2db50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68  ,F,S,L)] call th
2db60 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  at.**          r
2db70 65 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51  egistered the SQ
2db80 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63  L function assoc
2db90 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 20  iated with .**  
2dba0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2dbb0 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a  _context] C..*/.
2dbc0 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
2dbd0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
2dbe0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
2dbf0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
2dc00 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
2dc10 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b  Auxiliary Data {
2dc20 46 31 36 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F16270}.**.** Th
2dc30 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20  e following two 
2dc40 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
2dc50 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20   used by scalar 
2dc60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
2dc70 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
2dc80 74 61 2d 64 61 74 61 20 77 69 74 68 20 61 72 67  ta-data with arg
2dc90 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
2dca0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
2dcb0 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
2dcc0 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
2dcd0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2dce0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
2dcf0 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
2dd00 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
2dd10 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
2dd20 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
2dd30 20 6d 65 74 61 2d 64 61 74 61 20 6d 61 79 20 62   meta-data may b
2dd40 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
2dd50 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
2dd60 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
2dd70 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
2dd80 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
2dd90 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
2dda0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
2ddb0 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
2ddc0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
2ddd0 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
2dde0 20 61 73 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61   as.** meta-data
2ddf0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2de00 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
2de10 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
2de20 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
2de30 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
2de40 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
2de50 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
2de60 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
2de70 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
2de80 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2de90 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
2dea0 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
2deb0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
2dec0 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
2ded0 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
2dee0 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
2def0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
2df00 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2df10 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
2df20 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2df30 20 74 6f 20 74 68 65 20 6d 65 74 61 2d 64 61 74   to the meta-dat
2df40 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
2df50 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
2df60 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
2df70 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
2df80 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
2df90 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
2dfa0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2dfb0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20  function..** If 
2dfc0 6e 6f 20 6d 65 74 61 2d 64 61 74 61 20 68 61 73  no meta-data has
2dfd0 20 62 65 65 6e 20 65 76 65 72 20 62 65 65 6e 20   been ever been 
2dfe0 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 0a  set for the Nth.
2dff0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
2e000 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20  he function, or 
2e010 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  if the correspon
2e020 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
2e030 72 61 6d 65 74 65 72 0a 2a 2a 20 68 61 73 20 63  rameter.** has c
2e040 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65  hanged since the
2e050 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73   meta-data was s
2e060 65 74 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  et, then sqlite3
2e070 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a  _get_auxdata().*
2e080 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  * returns a NULL
2e090 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2e0a0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
2e0b0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
2e0c0 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
2e0d0 74 61 2d 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74  ta-data.** point
2e0e0 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64  ed to by its 3rd
2e0f0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
2e100 65 20 6d 65 74 61 2d 64 61 74 61 20 66 6f 72 20  e meta-data for 
2e110 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
2e120 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
2e130 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e140 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65  function.  Subse
2e150 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
2e160 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
2e170 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65  xdata() might re
2e180 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20  turn this data, 
2e190 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74  if it has.** not
2e1a0 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e   been destroyed.
2e1b0 20 0a 2a 2a 20 49 66 20 69 74 20 69 73 20 6e 6f   .** If it is no
2e1c0 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
2e1d0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
2e1e0 65 73 74 72 75 63 74 6f 72 20 0a 2a 2a 20 66 75  estructor .** fu
2e1f0 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
2e200 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2e210 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
2e220 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
2e230 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
2e240 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
2e250 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
2e260 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
2e270 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20  .** or when the 
2e280 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
2e290 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76  mpletes, whichev
2e2a0 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
2e2b0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  **.** SQLite is 
2e2c0 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65  free to call the
2e2d0 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20   destructor and 
2e2e0 64 72 6f 70 20 6d 65 74 61 2d 64 61 74 61 20 6f  drop meta-data o
2e2f0 6e 0a 2a 2a 20 61 6e 79 20 70 61 72 61 6d 65 74  n.** any paramet
2e300 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69  er of any functi
2e310 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20  on at any time. 
2e320 20 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e   The only guaran
2e330 74 65 65 0a 2a 2a 20 69 73 20 74 68 61 74 20 74  tee.** is that t
2e340 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69  he destructor wi
2e350 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66  ll be called bef
2e360 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61  ore the metadata
2e370 20 69 73 0a 2a 2a 20 64 72 6f 70 70 65 64 2e 0a   is.** dropped..
2e380 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63  **.** In practic
2e390 65 2c 20 6d 65 74 61 2d 64 61 74 61 20 69 73 20  e, meta-data is 
2e3a0 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
2e3b0 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
2e3c0 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
2e3d0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
2e3e0 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
2e3f0 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
2e400 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
2e410 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76  values and SQL v
2e420 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  ariables..**.** 
2e430 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2e440 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2e450 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2e460 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
2e470 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2e480 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
2e490 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2e4a0 0a 2a 2a 20 7b 46 31 36 32 37 32 7d 20 54 68 65  .** {F16272} The
2e4b0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
2e4c0 78 64 61 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65  xdata(C,N)] inte
2e4d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2e4e0 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
2e4f0 20 20 20 20 74 6f 20 6d 65 74 61 64 61 74 61 20      to metadata 
2e500 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2e510 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65  the Nth paramete
2e520 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  r of the SQL fun
2e530 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
2e540 20 20 77 68 6f 73 65 20 63 6f 6e 74 65 78 74 20    whose context 
2e550 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66  is C, or NULL if
2e560 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74   there is no met
2e570 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
2e580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
2e590 68 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  h that parameter
2e5a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 34 7d  ..**.** {F16274}
2e5b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
2e5c0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
2e5d0 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 73  D)] interface as
2e5e0 73 69 67 6e 73 20 61 20 6d 65 74 61 64 61 74 61  signs a metadata
2e5f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
2e600 6e 74 65 72 20 50 20 74 6f 20 74 68 65 20 4e 74  nter P to the Nt
2e610 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  h parameter of t
2e620 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2e630 77 69 74 68 20 63 6f 6e 74 65 78 74 0a 2a 2a 20  with context.** 
2e640 20 20 20 20 20 20 20 20 20 43 2e 0a 2a 2a 0a 2a           C..**.*
2e650 2a 20 7b 46 31 36 32 37 36 7d 20 53 51 4c 69 74  * {F16276} SQLit
2e660 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
2e670 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77  e destructor D w
2e680 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67  ith a single arg
2e690 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  ument.**        
2e6a0 20 20 77 68 69 63 68 20 69 73 20 74 68 65 20 6d    which is the m
2e6b0 65 74 61 64 61 74 61 20 70 6f 69 6e 74 65 72 20  etadata pointer 
2e6c0 50 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  P following a ca
2e6d0 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ll to.**        
2e6e0 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61    [sqlite3_set_a
2e6f0 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d  uxdata(C,N,P,D)]
2e700 20 77 68 65 6e 20 53 51 4c 69 74 65 20 63 65 61   when SQLite cea
2e710 73 65 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20  ses to hold.**  
2e720 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 74 61          the meta
2e730 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  data..**.** {F16
2e740 32 37 37 7d 20 53 51 4c 69 74 65 20 63 65 61 73  277} SQLite ceas
2e750 65 73 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64  es to hold metad
2e760 61 74 61 20 66 6f 72 20 61 6e 20 53 51 4c 20 66  ata for an SQL f
2e770 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
2e780 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  r.**          wh
2e790 65 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  en the value of 
2e7a0 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 63  that parameter c
2e7b0 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  hanges..**.** {F
2e7c0 31 36 32 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c  16278} When [sql
2e7d0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2e7e0 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e  (C,N,P,D)] is in
2e7f0 76 6f 6b 65 64 2c 20 74 68 65 20 64 65 73 74 72  voked, the destr
2e800 75 63 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  uctor.**        
2e810 20 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20    is called for 
2e820 61 6e 79 20 70 72 69 6f 72 20 6d 65 74 61 64 61  any prior metada
2e830 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
2e840 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  th the same func
2e850 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
2e860 20 63 6f 6e 74 65 78 74 20 43 20 61 6e 64 20 70   context C and p
2e870 61 72 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a  arameter N..**.*
2e880 2a 20 7b 46 31 36 32 37 39 7d 20 53 51 4c 69 74  * {F16279} SQLit
2e890 65 20 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74  e will call dest
2e8a0 72 75 63 74 6f 72 73 20 66 6f 72 20 61 6e 79 20  ructors for any 
2e8b0 6d 65 74 61 64 61 74 61 20 69 74 20 69 73 20 68  metadata it is h
2e8c0 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  olding.**       
2e8d0 20 20 20 69 6e 20 61 20 70 61 72 74 69 63 75 6c     in a particul
2e8e0 61 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ar [prepared sta
2e8f0 74 65 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20 65  tement] S when e
2e900 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
2e910 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74    [sqlite3_reset
2e920 28 53 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  (S)] or [sqlite3
2e930 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73  _finalize(S)] is
2e940 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64   called..*/.void
2e950 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
2e960 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
2e970 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
2e980 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
2e990 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
2e9a0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
2e9b0 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
2e9c0 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
2e9d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
2e9e0 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
2e9f0 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
2ea00 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 46 31 30  or Behavior {F10
2ea10 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  280}.**.** These
2ea20 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
2ea30 75 65 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  ue for the destr
2ea40 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
2ea50 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
2ea60 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
2ea70 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2ea80 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2ea90 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74  t_blob()].  If t
2eaa0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
2eab0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c   argument is SQL
2eac0 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d  ITE_STATIC, it m
2ead0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
2eae0 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73  ntent pointer is
2eaf0 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64   constant.** and
2eb00 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e   will never chan
2eb10 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74  ge.  It does not
2eb20 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74   need to be dest
2eb30 72 6f 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20  royed.  The .** 
2eb40 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2eb50 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61   value means tha
2eb60 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69  t the content wi
2eb70 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65  ll likely change
2eb80 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20   in.** the near 
2eb90 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20  future and that 
2eba0 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61  SQLite should ma
2ebb0 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ke its own priva
2ebc0 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68  te copy of.** th
2ebd0 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65  e content before
2ebe0 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
2ebf0 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73  * The typedef is
2ec00 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f   necessary to wo
2ec10 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65  rk around proble
2ec20 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a  ms in certain.**
2ec30 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20   C++ compilers. 
2ec40 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39   See ticket #219
2ec50 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  1..*/.typedef vo
2ec60 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
2ec70 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
2ec80 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
2ec90 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
2eca0 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
2ecb0 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
2ecc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
2ecd0 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
2ece0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
2ecf0 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
2ed00 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
2ed10 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
2ed20 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 46   SQL Function {F
2ed30 31 36 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  16400}.**.** The
2ed40 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2ed50 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
2ed60 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
2ed70 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
2ed80 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
2ed90 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2eda0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
2edb0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2edc0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
2edd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ede0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
2edf0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
2ee00 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
2ee10 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
2ee20 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
2ee30 6c 69 6b 65 20 74 68 65 20 0a 2a 2a 20 5b 73 71  like the .** [sq
2ee40 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2ee50 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
2ee60 5d 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  ] family of func
2ee70 74 69 6f 6e 73 20 75 73 65 64 0a 2a 2a 20 74 6f  tions used.** to
2ee80 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
2ee90 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
2eea0 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
2eeb0 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
2eec0 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   to the.** [sqli
2eed0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2eee0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 64  sqlite3_bind_* d
2eef0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
2ef00 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
2ef10 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
2ef20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2ef30 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
2ef40 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2ef50 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
2ef60 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
2ef70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2ef80 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
2ef90 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
2efa0 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
2efb0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
2efc0 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
2efd0 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
2efe0 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
2eff0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2f000 2e 20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  . .** The sqlite
2f010 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
2f020 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
2f030 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
2f040 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
2f050 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2f060 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
2f070 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
2f080 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
2f090 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
2f0a0 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
2f0b0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2f0c0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
2f0d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2f0e0 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
2f0f0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2f100 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
2f110 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
2f120 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
2f130 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
2f140 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
2f150 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
2f160 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
2f170 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2f180 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f190 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
2f1a0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
2f1b0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
2f1c0 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
2f1d0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
2f1e0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
2f1f0 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65  ption..** SQLite
2f200 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67   uses the string
2f210 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
2f220 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65  he.** 2nd parame
2f230 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72  ter of sqlite3_r
2f240 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
2f250 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f260 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20  error16().** as 
2f270 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65  the text of an e
2f280 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53  rror message.  S
2f290 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
2f2a0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
2f2b0 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f  ssage string fro
2f2c0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
2f2d0 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 38  _error() as UTF8
2f2e0 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65  . SQLite.** inte
2f2f0 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
2f300 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
2f310 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
2f320 61 73 20 55 54 46 31 36 20 69 6e 20 6e 61 74 69  as UTF16 in nati
2f330 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72  ve.** byte order
2f340 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 20  .  If the third 
2f350 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2f360 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f370 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
2f380 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2f390 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
2f3a0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
2f3b0 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
2f3c0 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
2f3d0 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
2f3e0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
2f3f0 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65  acter..** If the
2f400 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2f410 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
2f420 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
2f430 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f440 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
2f450 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
2f460 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
2f470 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
2f480 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
2f490 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
2f4a0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
2f4b0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
2f4c0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2f4d0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
2f4e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f4f0 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
2f500 6e 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  nes make a copy 
2f510 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
2f520 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
2f530 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
2f540 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
2f550 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
2f560 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
2f570 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
2f580 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
2f590 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
2f5a0 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
2f5b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2f5c0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
2f5d0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
2f5e0 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
2f5f0 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
2f600 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
2f610 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
2f620 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
2f630 20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20   By default,.** 
2f640 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69  the error code i
2f650 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  s SQLITE_ERROR. 
2f660 20 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   A subsequent ca
2f670 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
2f680 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
2f690 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2f6a0 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
2f6b0 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
2f6c0 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
2f6d0 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  R..**.** The sql
2f6e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
2f6f0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
2f700 61 75 73 65 73 20 53 51 4c 69 74 65 0a 2a 2a 20  auses SQLite.** 
2f710 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
2f720 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  r indicating tha
2f730 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
2f740 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 0a 2a 2a  OB is to long.**
2f750 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 20 20   to represent.  
2f760 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2f770 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  lt_nomem() inter
2f780 66 61 63 65 0a 2a 2a 20 63 61 75 73 65 73 20 53  face.** causes S
2f790 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
2f7a0 6e 20 65 78 63 65 70 74 69 6f 6e 20 69 6e 64 69  n exception indi
2f7b0 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20  cating that the 
2f7c0 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
2f7d0 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
2f7e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2f7f0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e  _result_int() in
2f800 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2f810 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
2f820 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2f830 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2f840 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33  tion to be the 3
2f850 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
2f860 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
2f870 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
2f880 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
2f890 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2f8a0 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  nt64() interface
2f8b0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
2f8c0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
2f8d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2f8e0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2f8f0 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73   be the 64-bit s
2f900 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
2f910 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
2f920 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
2f930 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2f940 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
2f950 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2f960 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2f970 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
2f980 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f990 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
2f9a0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ULL..**.** The s
2f9b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2f9c0 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  xt(), sqlite3_re
2f9d0 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 20 0a  sult_text16(), .
2f9e0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
2f9f0 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
2fa00 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2fa10 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
2fa20 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
2fa30 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
2fa40 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2fa50 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2fa60 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
2fa70 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
2fa80 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
2fa90 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
2faa0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2fab0 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
2fac0 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
2fad0 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
2fae0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
2faf0 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  ** SQLite takes 
2fb00 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
2fb10 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
2fb20 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
2fb30 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
2fb40 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
2fb50 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2fb60 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  faces..** If the
2fb70 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
2fb80 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2fb90 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2fba0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
2fbb0 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
2fbc0 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
2fbd0 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
2fbe0 20 70 61 72 61 6d 65 74 65 72 20 0a 2a 2a 20 74   parameter .** t
2fbf0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
2fc00 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
2fc10 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
2fc20 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2fc30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2fc40 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
2fc50 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
2fc60 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
2fc70 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
2fc80 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
2fc90 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
2fca0 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
2fcb0 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
2fcc0 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
2fcd0 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
2fce0 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a  unction result..
2fcf0 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61  ** If the 4th pa
2fd00 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2fd10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2fd20 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2fd30 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
2fd40 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
2fd50 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
2fd60 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
2fd70 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
2fd80 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
2fd90 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
2fda0 20 6f 72 20 62 6c 6f 62 20 72 65 73 75 6c 74 20   or blob result 
2fdb0 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
2fdc0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
2fdd0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66  at result..** If
2fde0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2fdf0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2fe00 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2fe10 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
2fe20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2fe30 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
2fe40 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
2fe50 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 0a  TE_STATIC, then.
2fe60 2a 2a 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  ** SQLite assume
2fe70 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20  s that the text 
2fe80 6f 72 20 62 6c 6f 62 20 72 65 73 75 6c 74 20 69  or blob result i
2fe90 73 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65  s constant space
2fea0 20 61 6e 64 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74   and.** does not
2feb0 20 63 6f 70 79 20 74 68 65 20 73 70 61 63 65 20   copy the space 
2fec0 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75  or call a destru
2fed0 63 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61 73  ctor when it has
2fee0 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
2fef0 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
2ff00 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61  ** If the 4th pa
2ff10 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2ff20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2ff30 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2ff40 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
2ff50 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
2ff60 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
2ff70 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
2ff80 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65  T.** then SQLite
2ff90 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
2ffa0 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
2ffb0 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20   space obtained 
2ffc0 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  from.** from [sq
2ffd0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
2ffe0 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
2fff0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
30000 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
30010 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
30020 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
30030 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
30040 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
30050 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
30060 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
30070 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30080 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
30090 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
300a0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
300b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
300c0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
300d0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
300e0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
300f0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
30100 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  hat [sqlite3_val
30110 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
30120 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
30130 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
30140 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
30150 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
30160 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
30170 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
30180 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65  ..** A [protecte
30190 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
301a0 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
301b0 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
301c0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
301d0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
301e0 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
301f0 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
30200 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
30210 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30220 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
30230 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
30240 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
30250 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
30260 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
30270 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
30280 20 74 68 72 65 61 64 20 0a 2a 2a 20 74 68 61 6e   thread .** than
30290 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
302a0 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
302b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
302c0 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
302d0 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
302e0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
302f0 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
30300 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
30310 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
30320 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 33 7d  :.**.** {F16403}
30330 20 54 68 65 20 64 65 66 61 75 6c 74 20 72 65 74   The default ret
30340 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 61  urn value from a
30350 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ny SQL function 
30360 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  is NULL..**.** {
30370 46 31 36 34 30 36 7d 20 54 68 65 20 5b 73 71 6c  F16406} The [sql
30380 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
30390 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
303a0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
303b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
303c0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
303d0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 20  ction C to be a 
303e0 62 6c 6f 62 20 74 68 61 74 20 69 73 20 4e 20 62  blob that is N b
303f0 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ytes.**         
30400 20 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20 77   in length and w
30410 69 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  ith content poin
30420 74 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a  ted to by V..**.
30430 2a 2a 20 7b 46 31 36 34 30 39 7d 20 54 68 65 20  ** {F16409} The 
30440 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
30450 64 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74  double(C,V)] int
30460 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
30470 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
30480 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
30490 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
304a0 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
304b0 6e 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a  nt value V..**.*
304c0 2a 20 7b 46 31 36 34 31 32 7d 20 54 68 65 20 5b  * {F16412} The [
304d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
304e0 72 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74  rror(C,V,N)] int
304f0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
30500 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  he return.**    
30510 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66        value of f
30520 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
30530 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
30540 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  h error code.** 
30550 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
30560 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54  _ERROR] and a UT
30570 46 38 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  F8 error message
30580 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75   copied from V u
30590 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  p to the.**     
305a0 20 20 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20       first zero 
305b0 62 79 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20  byte or until N 
305c0 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20 69  bytes are read i
305d0 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e  f N is positive.
305e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 35 7d 20  .**.** {F16415} 
305f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
30600 75 6c 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c  ult_error16(C,V,
30610 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  N)] interface ch
30620 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
30630 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
30640 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
30650 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
30660 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
30670 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
30680 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61  [SQLITE_ERROR] a
30690 6e 64 20 61 20 55 54 46 31 36 20 6e 61 74 69 76  nd a UTF16 nativ
306a0 65 20 62 79 74 65 20 6f 72 64 65 72 20 65 72 72  e byte order err
306b0 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20  or message.**   
306c0 20 20 20 20 20 20 20 63 6f 70 69 65 64 20 66 72         copied fr
306d0 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 20 66  om V up to the f
306e0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
306f0 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e 20  ator or until N 
30700 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  bytes.**        
30710 20 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20    are read if N 
30720 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a  is positive..**.
30730 2a 2a 20 7b 46 31 36 34 31 38 7d 20 54 68 65 20  ** {F16418} The 
30740 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
30750 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29 5d  error_toobig(C)]
30760 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
30770 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
30780 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
30790 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
307a0 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
307b0 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
307c0 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
307d0 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d   [SQLITE_TOOBIG]
307e0 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69   and an appropri
307f0 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ate error messag
30800 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 31  e..**.** {F16421
30810 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
30820 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
30830 6d 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20  m(C)] interface 
30840 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75  changes the retu
30850 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  rn.**          v
30860 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63  alue of the func
30870 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
30880 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
30890 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20  rror code.**    
308a0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e 4f        [SQLITE_NO
308b0 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70 72  MEM] and an appr
308c0 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65  opriate error me
308d0 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ssage..**.** {F1
308e0 36 34 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  6424} The [sqlit
308f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
30900 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74 65 72  code(C,E)] inter
30910 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
30920 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
30930 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65      value of the
30940 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
30950 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77  e an exception w
30960 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 20 45  ith error code E
30970 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 54 68  ..**          Th
30980 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
30990 74 65 78 74 20 69 73 20 75 6e 63 68 61 6e 67 65  text is unchange
309a0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 37  d..**.** {F16427
309b0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
309c0 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20  esult_int(C,V)] 
309d0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
309e0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
309f0 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
30a00 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
30a10 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 69 6e  be the 32-bit in
30a20 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a  teger value V..*
30a30 2a 0a 2a 2a 20 7b 46 31 36 34 33 30 7d 20 54 68  *.** {F16430} Th
30a40 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
30a50 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20 69 6e  t_int64(C,V)] in
30a60 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
30a70 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
30a80 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
30a90 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
30aa0 20 74 68 65 20 36 34 2d 62 69 74 20 69 6e 74 65   the 64-bit inte
30ab0 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a  ger value V..**.
30ac0 2a 2a 20 7b 46 31 36 34 33 33 7d 20 54 68 65 20  ** {F16433} The 
30ad0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
30ae0 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66 61  null(C)] interfa
30af0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
30b00 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
30b10 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
30b20 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c 4c  ion C to be NULL
30b30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 36 7d  ..**.** {F16436}
30b40 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
30b50 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c  sult_text(C,V,N,
30b60 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  D)] interface ch
30b70 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
30b80 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
30b90 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
30ba0 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 38 20   to be the UTF8 
30bb0 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
30bc0 20 20 20 56 20 75 70 20 74 6f 20 74 68 65 20 66     V up to the f
30bd0 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69  irst zero if N i
30be0 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20  s negative.**   
30bf0 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69         or the fi
30c00 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56  rst N bytes of V
30c10 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67   if N is non-neg
30c20 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ative..**.** {F1
30c30 36 34 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  6439} The [sqlit
30c40 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
30c50 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
30c60 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
30c70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
30c80 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
30c90 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
30ca0 65 20 55 54 46 31 36 20 6e 61 74 69 76 65 20 62  e UTF16 native b
30cb0 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20  yte order.**    
30cc0 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75        string V u
30cd0 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
30ce0 65 72 6f 20 69 66 20 4e 20 69 73 0a 2a 2a 20 20  ero if N is.**  
30cf0 20 20 20 20 20 20 20 20 6e 65 67 61 74 69 76 65          negative
30d00 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20   or the first N 
30d10 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20  bytes of V if N 
30d20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
30d30 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 32 7d 20  .**.** {F16442} 
30d40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
30d50 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56  ult_text16be(C,V
30d60 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
30d70 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
30d80 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
30d90 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
30da0 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
30db0 46 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a  F16 big-endian.*
30dc0 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
30dd0 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69  g V up to the fi
30de0 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73  rst zero if N is
30df0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
30e00 6e 65 67 61 74 69 76 65 20 6f 72 20 74 68 65 20  negative or the 
30e10 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 72  first N bytes or
30e20 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
30e30 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
30e40 46 31 36 34 34 35 7d 20 54 68 65 20 5b 73 71 6c  F16445} The [sql
30e50 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
30e60 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16le(C,V,N,D)] i
30e70 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
30e80 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30e90 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
30ea0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
30eb0 65 20 74 68 65 20 55 54 46 31 36 20 6c 69 74 74  e the UTF16 litt
30ec0 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  le-endian.**    
30ed0 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75        string V u
30ee0 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
30ef0 65 72 6f 20 69 66 20 4e 20 69 73 0a 2a 2a 20 20  ero if N is.**  
30f00 20 20 20 20 20 20 20 20 6e 65 67 61 74 69 76 65          negative
30f10 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20   or the first N 
30f20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20  bytes of V if N 
30f30 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
30f40 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 38 7d 20  .**.** {F16448} 
30f50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
30f60 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20  ult_value(C,V)] 
30f70 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
30f80 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
30f90 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
30fa0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
30fb0 62 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  be [unprotected 
30fc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
30fd0 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63  *          objec
30fe0 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  t V..**.** {F164
30ff0 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  51} The [sqlite3
31000 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
31010 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,N)] interface
31020 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
31030 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
31040 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
31050 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d 62  n C to be an N-b
31060 79 74 65 20 62 6c 6f 62 20 6f 66 20 61 6c 6c 20  yte blob of all 
31070 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  zeros..**.** {F1
31080 36 34 35 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  6454} The [sqlit
31090 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
310a0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
310b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
310c0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
310d0 74 65 72 66 61 63 65 73 20 6d 61 6b 65 20 61 20  terfaces make a 
310e0 63 6f 70 79 20 6f 66 20 74 68 65 69 72 20 65 72  copy of their er
310f0 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
31100 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20 20  ngs before.**   
31110 20 20 20 20 20 20 20 72 65 74 75 72 6e 69 6e 67         returning
31120 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 37 7d  ..**.** {F16457}
31130 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75   If the D destru
31140 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74  ctor parameter t
31150 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
31160 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d  t_blob(C,V,N,D)]
31170 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
31180 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31190 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73  xt(C,V,N,D)], [s
311a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
311b0 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  xt16(C,V,N,D)],.
311c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
311d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
311e0 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20  16be(C,V,N,D)], 
311f0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
31200 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31210 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29  ext16le(C,V,N,D)
31220 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e  ] is the constan
31230 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  t [SQLITE_STATIC
31240 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ].**          th
31250 65 6e 20 6e 6f 20 64 65 73 74 72 75 63 74 6f 72  en no destructor
31260 20 69 73 20 65 76 65 72 20 63 61 6c 6c 65 64 20   is ever called 
31270 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65 72 20 56  on the pointer V
31280 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20 20   and SQLite.**  
31290 20 20 20 20 20 20 20 20 61 73 73 75 6d 65 73 20          assumes 
312a0 74 68 61 74 20 56 20 69 73 20 69 6d 6d 75 74 61  that V is immuta
312b0 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ble..**.** {F164
312c0 36 30 7d 20 49 66 20 74 68 65 20 44 20 64 65 73  60} If the D des
312d0 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65  tructor paramete
312e0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  r to [sqlite3_re
312f0 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c  sult_blob(C,V,N,
31300 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
31310 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31320 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _text(C,V,N,D)],
31330 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31340 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
31350 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
31360 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31370 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29  ext16be(C,V,N,D)
31380 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
31390 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
313a0 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e  t_text16le(C,V,N
313b0 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73  ,D)] is the cons
313c0 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  tant.**         
313d0 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
313e0 4e 54 5d 20 74 68 65 6e 20 74 68 65 20 69 6e 74  NT] then the int
313f0 65 72 66 61 63 65 73 20 6d 61 6b 65 73 20 61 20  erfaces makes a 
31400 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20  copy of the.**  
31410 20 20 20 20 20 20 20 20 63 6f 6e 74 65 6e 74 20          content 
31420 6f 66 20 56 20 61 6e 64 20 72 65 74 61 69 6e 73  of V and retains
31430 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a   the copy..**.**
31440 20 7b 46 31 36 34 36 33 7d 20 49 66 20 74 68 65   {F16463} If the
31450 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61   D destructor pa
31460 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
31470 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
31480 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
31490 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
314a0 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c  result_text(C,V,
314b0 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  N,D)], [sqlite3_
314c0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c  result_text16(C,
314d0 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
314e0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
314f0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c  sult_text16be(C,
31500 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,N,D)], or.**  
31510 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
31520 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
31530 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73 6f  (C,V,N,D)] is so
31540 6d 65 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  me value other t
31550 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  han.**          
31560 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
31570 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 20 61 6e  QLITE_STATIC] an
31580 64 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  d [SQLITE_TRANSI
31590 45 4e 54 5d 20 74 68 65 6e 20 0a 2a 2a 20 20 20  ENT] then .**   
315a0 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 77 69         SQLite wi
315b0 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
315c0 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20  structor D with 
315d0 56 20 61 73 20 69 74 73 20 6f 6e 6c 79 20 61 72  V as its only ar
315e0 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  gument.**       
315f0 20 20 20 77 68 65 6e 20 69 74 20 68 61 73 20 66     when it has f
31600 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
31610 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69   V value..*/.voi
31620 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
31630 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  _blob(sqlite3_co
31640 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
31650 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
31660 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
31670 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
31680 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  ouble(sqlite3_co
31690 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b  ntext*, double);
316a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
316b0 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74  sult_error(sqlit
316c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
316d0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a  st char*, int);.
316e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
316f0 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69  ult_error16(sqli
31700 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
31710 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  nst void*, int);
31720 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
31730 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
31740 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
31750 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
31760 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
31770 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e  omem(sqlite3_con
31780 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
31790 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
317a0 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63  r_code(sqlite3_c
317b0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
317c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
317d0 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63  lt_int(sqlite3_c
317e0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
317f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
31800 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  lt_int64(sqlite3
31810 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
31820 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  e3_int64);.void 
31830 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
31840 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ull(sqlite3_cont
31850 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
31860 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
31870 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31880 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
31890 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
318a0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
318b0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
318c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
318d0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
318e0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
318f0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
31900 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
31910 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
31920 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
31930 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
31940 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
31950 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
31960 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
31970 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
31980 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
31990 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
319a0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
319b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
319c0 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
319d0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
319e0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
319f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31a00 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  *, int n);../*.*
31a10 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69  * CAPI3REF: Defi
31a20 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67  ne New Collating
31a30 20 53 65 71 75 65 6e 63 65 73 20 7b 46 31 36 36   Sequences {F166
31a40 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00}.**.** These 
31a50 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73  functions are us
31a60 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f  ed to add new co
31a70 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
31a80 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s to the.** [sql
31a90 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 70  ite3*] handle sp
31aa0 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
31ab0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 0a  irst argument. .
31ac0 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f  **.** The name o
31ad0 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74  f the new collat
31ae0 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20  ion sequence is 
31af0 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20 55  specified as a U
31b00 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66  TF-8 string.** f
31b10 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
31b20 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e  e_collation() an
31b30 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  d sqlite3_create
31b40 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a  _collation_v2().
31b50 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20  ** and a UTF-16 
31b60 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74  string for sqlit
31b70 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
31b80 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20  ion16(). In all 
31b90 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  cases.** the nam
31ba0 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74  e is passed as t
31bb0 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
31bc0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
31bd0 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67  ** The third arg
31be0 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65  ument may be one
31bf0 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
31c00 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  s [SQLITE_UTF8],
31c10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
31c20 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  6LE] or [SQLITE_
31c30 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61  UTF16BE], indica
31c40 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 73  ting that the us
31c50 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72  er-supplied.** r
31c60 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74  outine expects t
31c70 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e  o be passed poin
31c80 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
31c90 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
31ca0 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  F-8,.** UTF-16 l
31cb0 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 6f 72 20  ittle-endian or 
31cc0 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
31cd0 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  n respectively. 
31ce0 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67  The.** third arg
31cf0 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f  ument might also
31d00 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   be [SQLITE_UTF1
31d10 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e  6_ALIGNED] to in
31d20 64 69 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74  dicate that.** t
31d30 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63  he routine expec
31d40 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31  ts pointers to 1
31d50 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e  6-bit word align
31d60 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66  ed strings.** of
31d70 20 55 54 46 31 36 20 69 6e 20 74 68 65 20 6e 61   UTF16 in the na
31d80 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
31d90 6f 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70  of the host comp
31da0 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f  uter..**.** A po
31db0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65  inter to the use
31dc0 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  r supplied routi
31dd0 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  ne must be passe
31de0 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a  d as the fifth.*
31df0 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20  * argument.  If 
31e00 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73  it is NULL, this
31e10 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
31e20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c  deleting the col
31e30 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
31e40 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69  ce (so that SQLi
31e50 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69  te cannot call i
31e60 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45  t anymore)..** E
31e70 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70  ach time the app
31e80 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  lication.** supp
31e90 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  lied function is
31ea0 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20   invoked, it is 
31eb0 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66  passed a copy of
31ec0 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65   the void* passe
31ed0 64 20 61 73 0a 2a 2a 20 74 68 65 20 66 6f 75 72  d as.** the four
31ee0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
31ef0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
31f00 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 0a 2a 2a 20  llation() or.** 
31f10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
31f20 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 20 61 73 20  ollation16() as 
31f30 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  its first parame
31f40 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72  ter..**.** The r
31f50 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e  emaining argumen
31f60 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ts to the applic
31f70 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72  ation-supplied r
31f80 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73  outine are two s
31f90 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20  trings,.** each 
31fa0 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
31fb0 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20   (length, data) 
31fc0 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64  pair and encoded
31fd0 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
31fe0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73  .** that was pas
31ff0 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
32000 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74   argument when t
32010 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  he collation seq
32020 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67  uence was.** reg
32030 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 54  istered. {END} T
32040 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
32050 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
32060 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a   routine should.
32070 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69  ** return negati
32080 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69  ve, zero or posi
32090 74 69 76 65 20 69 66 0a 2a 2a 20 74 68 65 20 66  tive if.** the f
320a0 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c  irst string is l
320b0 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20  ess than, equal 
320c0 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
320d0 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  han the second.*
320e0 2a 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28  * string. i.e. (
320f0 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47  STRING1 - STRING
32100 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  2)..**.** The sq
32110 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
32120 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
32130 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
32140 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
32150 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
32160 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74   it takes an ext
32170 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ra argument whic
32180 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  h is a destructo
32190 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c  r for.** the col
321a0 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73  lation.  The des
321b0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
321c0 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  d when the colla
321d0 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72  tion is.** destr
321e0 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73  oyed and is pass
321f0 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ed a copy of the
32200 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
32210 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a  r void* pointer.
32220 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
32230 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
32240 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c  on_v2()..** Coll
32250 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72  ations are destr
32260 6f 79 65 64 20 77 68 65 6e 0a 2a 2a 20 74 68 65  oyed when.** the
32270 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
32280 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20   by later calls 
32290 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  to the collation
322a0 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
322b0 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74  ons.** or when t
322c0 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61  he [sqlite3*] da
322d0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69 73  tabase handle is
322e0 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73   closed using [s
322f0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
32300 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
32310 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 33  S:.**.** {F16603
32320 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
32330 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  all to the.**   
32340 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
32350 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32360 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
32370 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20  ] interface.**  
32380 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
32390 73 20 66 75 6e 63 74 69 6f 6e 20 46 20 61 73 20  s function F as 
323a0 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66  the comparison f
323b0 75 6e 63 74 69 6f 6e 20 75 73 65 64 20 74 6f 0a  unction used to.
323c0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d 70 6c  **          impl
323d0 65 6d 65 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e 20  ement collation 
323e0 58 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  X on [database c
323f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72  onnection] B for
32400 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74  .**          dat
32410 61 62 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e  abases having en
32420 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20  coding E..**.** 
32430 7b 46 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20  {F16604} SQLite 
32440 75 6e 64 65 72 73 74 61 6e 64 73 20 74 68 65 20  understands the 
32450 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  X parameter to.*
32460 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
32470 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32480 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
32490 46 2c 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d  F,D)] as a zero-
324a0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
324b0 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72         UTF-8 str
324c0 69 6e 67 20 69 6e 20 77 68 69 63 68 20 63 61 73  ing in which cas
324d0 65 20 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72  e is ignored for
324e0 20 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72   ASCII character
324f0 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  s and.**        
32500 20 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74    is significant
32510 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63   for non-ASCII c
32520 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
32530 20 7b 46 31 36 36 30 36 7d 20 53 75 63 63 65 73   {F16606} Succes
32540 73 69 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  sive calls to [s
32550 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32560 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
32570 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20  ,P,F,D)].**     
32580 20 20 20 20 20 77 69 74 68 20 74 68 65 20 73 61       with the sa
32590 6d 65 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c  me values for B,
325a0 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72   X, and E, overr
325b0 69 64 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73  ide prior values
325c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
325d0 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a  P, F, and D..**.
325e0 2a 2a 20 7b 46 31 36 36 30 39 7d 20 54 68 65 20  ** {F16609} The 
325f0 64 65 73 74 72 75 63 74 6f 72 20 44 20 69 6e 20  destructor D in 
32600 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32610 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
32620 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20  ,E,P,F,D)].**   
32630 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20 4e 55         is not NU
32640 4c 4c 20 74 68 65 6e 20 69 74 20 69 73 20 63 61  LL then it is ca
32650 6c 6c 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  lled with argume
32660 6e 74 20 50 20 77 68 65 6e 20 74 68 65 0a 2a 2a  nt P when the.**
32670 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74            collat
32680 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
32690 64 72 6f 70 70 65 64 20 62 79 20 53 51 4c 69 74  dropped by SQLit
326a0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 32  e..**.** {F16612
326b0 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  } A collating fu
326c0 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65  nction is droppe
326d0 64 20 77 68 65 6e 20 69 74 20 69 73 20 6f 76 65  d when it is ove
326e0 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  rloaded..**.** {
326f0 46 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61 74  F16615} A collat
32700 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
32710 64 72 6f 70 70 65 64 20 77 68 65 6e 20 74 68 65  dropped when the
32720 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
32730 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
32740 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
32750 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
32760 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31  )]..**.** {F1661
32770 38 7d 20 54 68 65 20 70 6f 69 6e 74 65 72 20 50  8} The pointer P
32780 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   in [sqlite3_cre
32790 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
327a0 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a  (B,X,E,P,F,D)].*
327b0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70 61  *          is pa
327c0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
327d0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
327e0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6d 70 61  ter to the compa
327f0 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  rison.**        
32800 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72    function F for
32810 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
32820 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 46  invocations of F
32830 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 31 7d  ..**.** {F16621}
32840 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   A call to [sqli
32850 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32860 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d  tion(B,X,E,P,F)]
32870 20 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20   is exactly.**  
32880 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
32890 20 61 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   as a call to [s
328a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
328b0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77 69  llation_v2()] wi
328c0 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
328d0 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65  he same paramete
328e0 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64 65  rs and a NULL de
328f0 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  structor..**.** 
32900 7b 46 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 69  {F16624} Followi
32910 6e 67 20 61 20 5b 73 71 6c 69 74 65 33 5f 63 72  ng a [sqlite3_cr
32920 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
32930 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c  2(B,X,E,P,F,D)],
32940 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
32950 69 74 65 20 75 73 65 73 20 74 68 65 20 63 6f 6d  ite uses the com
32960 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e  parison function
32970 20 46 20 66 6f 72 20 61 6c 6c 20 74 65 78 74 20   F for all text 
32980 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20  comparison.**   
32990 20 20 20 20 20 20 20 6f 70 65 72 61 74 69 6f 6e         operation
329a0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
329b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20  onnection] B on 
329c0 74 65 78 74 20 76 61 6c 75 65 73 20 74 68 61 74  text values that
329d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65  .**          use
329e0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73   the collating s
329f0 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 58 2e 0a  equence name X..
32a00 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 37 7d 20 54  **.** {F16627} T
32a10 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
32a20 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 42  te_collation16(B
32a30 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b 73  ,X,E,P,F)] works
32a40 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
32a50 20 20 20 20 20 20 61 73 20 5b 73 71 6c 69 74 65        as [sqlite
32a60 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
32a70 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 65  on(B,X,E,P,F)] e
32a80 78 63 65 70 74 20 74 68 61 74 20 74 68 65 0a 2a  xcept that the.*
32a90 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
32aa0 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20 75  tion name X is u
32ab0 6e 64 65 72 73 74 6f 6f 64 20 61 73 20 55 54 46  nderstood as UTF
32ac0 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79  -16 in native by
32ad0 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20  te order.**     
32ae0 20 20 20 20 20 69 6e 73 74 65 61 64 20 6f 66 20       instead of 
32af0 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  UTF-8..**.** {F1
32b00 36 36 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74 69  6630} When multi
32b10 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66  ple comparison f
32b20 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 76 61  unctions are ava
32b30 69 6c 61 62 6c 65 20 66 6f 72 20 74 68 65 20 73  ilable for the s
32b40 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
32b50 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
32b60 63 65 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f 73  ce, SQLite choos
32b70 65 73 20 74 68 65 20 6f 6e 65 20 77 68 6f 73 65  es the one whose
32b80 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
32b90 2a 20 20 20 20 20 20 20 20 20 20 72 65 71 75 69  *          requi
32ba0 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  res the least am
32bb0 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73 69  ount of conversi
32bc0 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64 65 66 61  on from the defa
32bd0 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ult.**          
32be0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66  text encoding of
32bf0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a   the database..*
32c00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
32c10 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a  eate_collation(.
32c20 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
32c30 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
32c40 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
32c50 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
32c60 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
32c70 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
32c80 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
32c90 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
32ca0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32cb0 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
32cc0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
32cd0 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
32ce0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
32cf0 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
32d00 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
32d10 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
32d20 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20  ,const void*),. 
32d30 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
32d40 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73  (void*).);.int s
32d50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32d60 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  llation16(.  sql
32d70 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
32d80 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
32d90 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
32da0 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
32db0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
32dc0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
32dd0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
32de0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32df0 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
32e00 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b  eded Callbacks {
32e10 46 31 36 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f  F16700}.**.** To
32e20 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
32e30 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
32e40 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
32e50 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
32e60 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
32e70 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
32e80 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
32e90 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
32ea0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 74   with the.** dat
32eb0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20  abase handle to 
32ec0 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76  be called whenev
32ed0 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
32ee0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
32ef0 63 65 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 65  ce is.** require
32f00 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
32f10 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
32f20 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
32f30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
32f40 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
32f50 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
32f60 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
32f70 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
32f80 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
32f90 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
32fa0 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
32fb0 20 7b 46 31 36 37 30 33 7d 20 49 66 20 73 71 6c   {F16703} If sql
32fc0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
32fd0 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
32fe0 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a 20  d, the names.** 
32ff0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
33000 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
33010 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
33020 72 2e 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74  r. A call to eit
33030 68 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  her.** function 
33040 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69  replaces any exi
33050 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a  sting callback..
33060 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
33070 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
33080 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
33090 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
330a0 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
330b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
330c0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
330d0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
330e0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
330f0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
33100 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
33110 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
33120 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64  database.** hand
33130 6c 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  le.  The third a
33140 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
33150 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
33160 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
33170 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6BE], or [SQLITE
33180 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
33190 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 0a 2a  ating the most.*
331a0 2a 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  * desirable form
331b0 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
331c0 6e 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  n sequence funct
331d0 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ion required..**
331e0 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
331f0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
33200 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75  e of the.** requ
33210 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ired collation s
33220 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  equence..**.** T
33230 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
33240 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
33250 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
33260 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
33270 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
33280 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
33290 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
332a0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
332b0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
332c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
332d0 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  n_v2()]..**.** I
332e0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
332f0 20 7b 46 31 36 37 30 32 7d 20 41 20 73 75 63 63   {F16702} A succ
33300 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
33310 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33320 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c 46 29 5d  n_needed(D,P,F)]
33330 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
33340 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
33350 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44 2c 50 2c  on_needed16(D,P,
33360 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20 20  F)] causes.**   
33370 20 20 20 20 20 20 20 74 68 65 20 5b 64 61 74 61         the [data
33380 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33390 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61 6c   D to invoke cal
333a0 6c 62 61 63 6b 20 46 20 77 69 74 68 20 66 69 72  lback F with fir
333b0 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  st.**          p
333c0 61 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65  arameter P whene
333d0 76 65 72 20 69 74 20 6e 65 65 64 73 20 61 20 63  ver it needs a c
333e0 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
333f0 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20 20  on for a.**     
33400 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73       collating s
33410 65 71 75 65 6e 63 65 20 74 68 61 74 20 69 74 20  equence that it 
33420 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61 62  does not know ab
33430 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37  out..**.** {F167
33440 30 34 7d 20 45 61 63 68 20 73 75 63 63 65 73 73  04} Each success
33450 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
33460 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
33470 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20 20  eeded()] or.**  
33480 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
33490 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
334a0 64 31 36 28 29 5d 20 6f 76 65 72 72 69 64 65 73  d16()] overrides
334b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
334c0 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20  gistered.**     
334d0 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65       on the same
334e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
334f0 63 74 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72 20  ction] by prior 
33500 63 61 6c 6c 73 20 74 6f 20 65 69 74 68 65 72 0a  calls to either.
33510 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
33520 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  rface..**.** {F1
33530 36 37 30 36 7d 20 54 68 65 20 6e 61 6d 65 20 6f  6706} The name o
33540 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  f the requested 
33550 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
33560 6f 6e 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  on passed in the
33570 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 34 74 68  .**          4th
33580 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
33590 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
335a0 20 55 54 46 2d 38 20 69 66 20 74 68 65 20 63 61   UTF-8 if the ca
335b0 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
335c0 20 20 20 77 61 73 20 72 65 67 69 73 74 65 72 65     was registere
335d0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
335e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
335f0 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20  d()] and.**     
33600 20 20 20 20 20 69 73 20 69 6e 20 55 54 46 2d 31       is in UTF-1
33610 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
33620 64 65 72 20 69 66 20 74 68 65 20 63 61 6c 6c 62  der if the callb
33630 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20 20  ack was.**      
33640 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 75      registered u
33650 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
33660 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
33670 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 0a 2a 2f 0a 69  ()]..**.** .*/.i
33680 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
33690 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
336a0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
336b0 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
336c0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
336d0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
336e0 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  char*).);.int sq
336f0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
33700 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
33710 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
33720 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
33730 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
33740 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
33750 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  *).);../*.** Spe
33760 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72  cify the key for
33770 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61   an encrypted da
33780 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f  tabase.  This ro
33790 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a  utine should be.
337a0 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20  ** called right 
337b0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70  after sqlite3_op
337c0 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  en()..**.** The 
337d0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
337e0 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
337f0 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
33800 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
33810 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
33820 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  */.int sqlite3_k
33830 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
33840 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
33850 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
33860 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
33870 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
33880 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
33890 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f     /* The key */
338a0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67  .);../*.** Chang
338b0 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20  e the key on an 
338c0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20  open database.  
338d0 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  If the current d
338e0 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a  atabase is not.*
338f0 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69  * encrypted, thi
33900 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65  s routine will e
33910 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70  ncrypt it.  If p
33920 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d  New==0 or nNew==
33930 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  0, the.** databa
33940 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e  se is decrypted.
33950 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
33960 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
33970 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
33980 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
33990 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
339a0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
339b0 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28  t sqlite3_rekey(
339c0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
339d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
339e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
339f0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
33a00 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
33a10 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
33a20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a  /* The new key *
33a30 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
33a40 33 52 45 46 3a 20 20 53 75 73 70 65 6e 64 20 45  3REF:  Suspend E
33a50 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
33a60 68 6f 72 74 20 54 69 6d 65 20 7b 46 31 30 35 33  hort Time {F1053
33a70 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
33a80 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e  ite3_sleep() fun
33a90 63 74 69 6f 6e 0a 2a 2a 20 63 61 75 73 65 73 20  ction.** causes 
33aa0 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
33ab0 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78  ad to suspend ex
33ac0 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61  ecution.** for a
33ad0 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72  t least a number
33ae0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
33af0 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74   specified in it
33b00 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  s parameter..**.
33b10 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74  ** If the operat
33b20 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20  ing system does 
33b30 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65  not support slee
33b40 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 20  p requests with 
33b50 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20  .** millisecond 
33b60 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  time resolution,
33b70 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77   then the time w
33b80 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75  ill be rounded u
33b90 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65 61  p to .** the nea
33ba0 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65  rest second. The
33bb0 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
33bc0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
33bd0 20 61 63 74 75 61 6c 6c 79 20 0a 2a 2a 20 72 65   actually .** re
33be0 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
33bf0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
33c00 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
33c10 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c  *.** SQLite impl
33c20 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65  ements this inte
33c30 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67  rface by calling
33c40 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a   the xSleep().**
33c50 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
33c60 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
33c70 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  vfs] object..**.
33c80 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
33c90 2a 0a 2a 2a 20 7b 46 31 30 35 33 33 7d 20 54 68  *.** {F10533} Th
33ca0 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  e [sqlite3_sleep
33cb0 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69  (M)] interface i
33cc0 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 65  nvokes the xSlee
33cd0 70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65  p.**          me
33ce0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
33cf0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
33d00 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74  |VFS] in order t
33d10 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75  o.**          su
33d20 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 20  spend execution 
33d30 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  of the current t
33d40 68 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65 61  hread for at lea
33d50 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d  st.**          M
33d60 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a   milliseconds..*
33d70 2a 0a 2a 2a 20 7b 46 31 30 35 33 36 7d 20 54 68  *.** {F10536} Th
33d80 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  e [sqlite3_sleep
33d90 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (M)] interface r
33da0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
33db0 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r of.**         
33dc0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
33dd0 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20   sleep actually 
33de0 72 65 71 75 65 73 74 65 64 20 6f 66 20 74 68 65  requested of the
33df0 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20   operating.**   
33e00 20 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20 77         system, w
33e10 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c 61  hich might be la
33e20 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 70 61  rger than the pa
33e30 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e  rameter M..*/.in
33e40 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  t sqlite3_sleep(
33e50 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
33e60 49 33 52 45 46 3a 20 20 4e 61 6d 65 20 4f 66 20  I3REF:  Name Of 
33e70 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
33e80 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c  ng Temporary Fil
33e90 65 73 20 7b 46 31 30 33 31 30 7d 0a 2a 2a 0a 2a  es {F10310}.**.*
33ea0 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  * If this global
33eb0 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
33ec0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
33ed0 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
33ee0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
33ef0 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
33f00 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
33f10 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
33f20 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
33f30 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  by SQLite will b
33f40 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
33f50 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20   directory.  If 
33f60 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
33f70 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
33f80 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 64 6f  , then SQLite do
33f90 65 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20  es a search for 
33fa0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 74  an appropriate t
33fb0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 69 6c 65  emporary.** file
33fc0 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
33fd0 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
33fe0 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20   to modify this 
33ff0 76 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20  variable once a 
34000 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34010 69 6f 6e 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20  ion.** has been 
34020 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73 20 69  opened.  It is i
34030 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
34040 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
34050 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
34060 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
34070 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
34080 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
34090 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
340a0 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
340b0 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69  n call and remai
340c0 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68 65 72  n unchanged ther
340d0 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54  eafter..*/.SQLIT
340e0 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
340f0 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
34100 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
34110 50 49 33 52 45 46 3a 20 20 54 65 73 74 20 54 6f  PI3REF:  Test To
34120 20 53 65 65 20 49 66 20 54 68 65 20 44 61 74 61   See If The Data
34130 62 61 73 65 20 49 73 20 49 6e 20 41 75 74 6f 2d  base Is In Auto-
34140 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 46 31 32  Commit Mode {F12
34150 39 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  930}.**.** The s
34160 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
34170 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  ommit() interfac
34180 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  e returns non-ze
34190 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66  ro or.** zero if
341a0 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62   the given datab
341b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
341c0 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
341d0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a  utocommit mode,.
341e0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
341f0 20 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f     Autocommit mo
34200 64 65 20 69 73 20 6f 6e 0a 2a 2a 20 62 79 20 64  de is on.** by d
34210 65 66 61 75 6c 74 2e 20 20 41 75 74 6f 63 6f 6d  efault.  Autocom
34220 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61  mit mode is disa
34230 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e  bled by a [BEGIN
34240 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
34250 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
34260 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79  is re-enabled by
34270 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b   a [COMMIT] or [
34280 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a  ROLLBACK]..**.**
34290 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64   If certain kind
342a0 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75  s of errors occu
342b0 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74  r on a statement
342c0 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d   within a multi-
342d0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61  statement.** tra
342e0 6e 73 61 63 74 69 6f 6e 73 20 28 65 72 72 6f 72  nsactions (error
342f0 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c  s including [SQL
34300 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_FULL], [SQLI
34310 54 45 5f 49 4f 45 52 52 5d 2c 20 0a 2a 2a 20 5b  TE_IOERR], .** [
34320 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b  SQLITE_NOMEM], [
34330 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e  SQLITE_BUSY], an
34340 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  d [SQLITE_INTERR
34350 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a  UPT]) then the.*
34360 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69  * transaction mi
34370 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ght be rolled ba
34380 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
34390 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20  .  The only way 
343a0 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 69  to.** find out i
343b0 66 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  f SQLite automat
343c0 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
343d0 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
343e0 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
343f0 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
34400 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
34410 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
34420 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 31 7d 20 54  **.** {F12931} T
34430 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  he [sqlite3_get_
34440 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69  autocommit(D)] i
34450 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
34460 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
34470 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 69 66           zero if
34480 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
34490 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73 20  onnection] D is 
344a0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
344b0 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20  ocommit.**      
344c0 20 20 20 20 6d 6f 64 65 2c 20 72 65 73 70 65 63      mode, respec
344d0 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  tively..**.** {F
344e0 31 32 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69  12932} Autocommi
344f0 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
34500 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b  default..**.** {
34510 46 31 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d  F12933} Autocomm
34520 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
34530 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73  led by a success
34540 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  ful [BEGIN] stat
34550 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ement..**.** {F1
34560 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74  2934} Autocommit
34570 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
34580 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c   by a successful
34590 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
345a0 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20  LLBACK].**      
345b0 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a      statement..*
345c0 2a 20 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  * .**.** LIMITAT
345d0 49 4f 4e 53 3a 0a 2a 2a 2a 0a 2a 2a 20 7b 55 31  IONS:.***.** {U1
345e0 32 39 33 36 7d 20 49 66 20 61 6e 6f 74 68 65 72  2936} If another
345f0 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
34600 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
34610 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
34620 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20  abase.**        
34630 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69    connection whi
34640 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  le this routine 
34650 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e  is running, then
34660 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
34670 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  e.**          is
34680 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69   undefined..*/.i
34690 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  nt sqlite3_get_a
346a0 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65  utocommit(sqlite
346b0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
346c0 33 52 45 46 3a 20 20 46 69 6e 64 20 54 68 65 20  3REF:  Find The 
346d0 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
346e0 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
346f0 61 74 65 6d 65 6e 74 20 7b 46 31 33 31 32 30 7d  atement {F13120}
34700 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
34710 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74  e3_db_handle int
34720 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
34730 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d  s the [sqlite3*]
34740 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
34750 20 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a 20 5b   to which a.** [
34760 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34770 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20  nt] belongs..** 
34780 54 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  The database han
34790 64 6c 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  dle returned by 
347a0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
347b0 65 0a 2a 2a 20 69 73 20 74 68 65 20 73 61 6d 65  e.** is the same
347c0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
347d0 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 74 68 65   that was.** the
347e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
347f0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
34800 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
34810 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a   its variants.**
34820 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74   that was used t
34830 6f 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  o create the sta
34840 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
34850 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  rst place..**.**
34860 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
34870 2a 2a 20 7b 46 31 33 31 32 33 7d 20 54 68 65 20  ** {F13123} The 
34880 5b 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  [sqlite3_db_hand
34890 6c 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  le(S)] interface
348a0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
348b0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
348c0 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
348d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f  connection] asso
348e0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20  ciated with.**  
348f0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
34900 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
34910 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
34920 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
34930 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
34940 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
34950 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72  Find the next pr
34960 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34970 20 7b 46 31 33 31 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F13140}.**.** 
34980 52 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  Return a pointer
34990 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72   to the next [pr
349a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
349b0 5d 20 61 66 74 65 72 20 70 53 74 6d 74 0a 2a 2a  ] after pStmt.**
349c0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
349d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
349e0 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20  ction] pDb.  If 
349f0 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a  pStmt is NULL.**
34a00 20 74 68 65 6e 20 72 65 74 75 72 6e 20 61 20 70   then return a p
34a10 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69  ointer to the fi
34a20 72 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  rst [prepared st
34a30 61 74 65 6d 65 6e 74 5d 20 61 73 73 6f 63 69 61  atement] associa
34a40 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
34a50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34a60 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 6e  tion] pDb.  If n
34a70 6f 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  o [prepared stat
34a80 65 6d 65 6e 74 5d 0a 2a 2a 20 73 61 74 69 73 66  ement].** satisf
34a90 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f  ies the conditio
34aa0 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  ns of this routi
34ab0 6e 65 2c 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e  ne, return NULL.
34ac0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
34ad0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 34 33  S:.**.** {F13143
34ae0 7d 20 49 66 20 44 20 69 73 20 61 20 5b 64 61 74  } If D is a [dat
34af0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34b00 5d 20 74 68 61 74 20 68 6f 6c 64 73 20 6f 6e 65  ] that holds one
34b10 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20   or more.**     
34b20 20 20 20 20 20 75 6e 66 69 6e 61 6c 69 7a 65 64       unfinalized
34b30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
34b40 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20 69 73 20  ments] and S is 
34b50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 0a  a NULL pointer,.
34b60 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
34b70 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
34b80 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69  tmt(D, S)] routi
34b90 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  ne shall return 
34ba0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20  a pointer.**    
34bb0 20 20 20 20 20 20 74 6f 20 6f 6e 65 20 6f 66 20        to one of 
34bc0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
34bd0 61 74 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69  atements] associ
34be0 61 74 65 64 20 77 69 74 68 20 44 2e 0a 2a 2a 0a  ated with D..**.
34bf0 2a 2a 20 7b 46 31 33 31 34 36 7d 20 49 66 20 44  ** {F13146} If D
34c00 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
34c10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
34c20 20 68 6f 6c 64 73 20 6e 6f 0a 2a 2a 20 20 20 20   holds no.**    
34c30 20 20 20 20 20 20 75 6e 66 69 6e 61 6c 69 7a 65        unfinalize
34c40 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
34c50 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20 69 73  ements] and S is
34c60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
34c70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
34c80 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  n [sqlite3_next_
34c90 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74  stmt(D, S)] rout
34ca0 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ine shall return
34cb0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20   a NULL.**      
34cc0 20 20 20 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a      pointer..**.
34cd0 2a 2a 20 7b 46 31 33 31 34 39 7d 20 49 66 20 53  ** {F13149} If S
34ce0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
34cf0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 5b 64  statement] in [d
34d00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34d10 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20  on] D.**        
34d20 20 20 61 6e 64 20 53 20 69 73 20 6e 6f 74 20 74    and S is not t
34d30 68 65 20 6c 61 73 74 20 5b 70 72 65 70 61 72 65  he last [prepare
34d40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
34d50 44 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  D, then.**      
34d60 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78      [sqlite3_nex
34d70 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f  t_stmt(D, S)] ro
34d80 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75  utine shall retu
34d90 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  rn a pointer.** 
34da0 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20           to the 
34db0 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73  next [prepared s
34dc0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 44 20 61  tatement] in D a
34dd0 66 74 65 72 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46  fter S..**.** {F
34de0 31 33 31 35 32 7d 20 49 66 20 53 20 69 73 20 74  13152} If S is t
34df0 68 65 20 6c 61 73 74 20 5b 70 72 65 70 61 72 65  he last [prepare
34e00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
34e10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34e20 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20  tion] D.**      
34e30 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
34e40 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53  3_next_stmt(D, S
34e50 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c  )] routine shall
34e60 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 0a 2a   return a NULL.*
34e70 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
34e80 65 72 2e 0a 2a 2a 0a 2a 2f 0a 73 71 6c 69 74 65  er..**.*/.sqlite
34e90 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f  3_stmt *sqlite3_
34ea0 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65  next_stmt(sqlite
34eb0 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f  3 *pDb, sqlite3_
34ec0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 0a  stmt *pStmt);...
34ed0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34ee0 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62  Commit And Rollb
34ef0 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  ack Notification
34f00 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39   Callbacks {F129
34f10 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  50}.**.** The sq
34f20 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
34f30 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
34f40 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
34f50 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
34f60 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
34f70 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
34f80 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64  ion is committed
34f90 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
34fa0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
34fb0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
34fc0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
34fd0 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
34fe0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
34ff0 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
35000 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  den..** The sqli
35010 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
35020 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
35030 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
35040 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
35050 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
35060 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
35070 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64  ion is committed
35080 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
35090 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
350a0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
350b0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
350c0 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
350d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
350e0 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
350f0 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67  den..** The pArg
35100 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73   argument is pas
35110 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 74  sed through.** t
35120 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20  o the callback. 
35130 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
35140 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f   on a commit hoo
35150 6b 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 72  k function .** r
35160 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
35170 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
35180 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
35190 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
351a0 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
351b0 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65  function was pre
351c0 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
351d0 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20  ed, its.** pArg 
351e0 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
351f0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55  d.  Otherwise NU
35200 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  LL is returned..
35210 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e  **.** Registerin
35220 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f  g a NULL functio
35230 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  n disables the c
35240 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46  allback..**.** F
35250 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
35260 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74  of this API, a t
35270 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61  ransaction is sa
35280 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 20  id to have been 
35290 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
352a0 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22  if an explicit "
352b0 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d  ROLLBACK" statem
352c0 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c  ent is executed,
352d0 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20   or.** an error 
352e0 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61  or constraint ca
352f0 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74  uses an implicit
35300 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63   rollback to occ
35310 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62  ur..** The rollb
35320 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
35330 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
35340 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
35350 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
35360 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63   rolled back bec
35370 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73  ause the databas
35380 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
35390 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72  closed..** The r
353a0 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
353b0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
353c0 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
353d0 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61   is.** rolled ba
353e0 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d  ck because a com
353f0 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  mit callback ret
35400 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a  urned non-zero..
35410 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20  ** <todo> Check 
35420 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a  on this </todo>.
35430 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
35440 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
35450 65 72 66 61 63 65 73 20 61 6e 64 20 61 72 65 20  erfaces and are 
35460 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
35470 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
35480 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  NTS:.**.** {F129
35490 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  51} The [sqlite3
354a0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46  _commit_hook(D,F
354b0 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
354c0 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20  egisters the.** 
354d0 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
354e0 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20  k function F to 
354f0 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
35500 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65  argument P whene
35510 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ver.**          
35520 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  a transaction co
35530 6d 6d 69 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  mmits on [databa
35540 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
35550 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 32 7d  ..**.** {F12952}
35560 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
35570 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  mmit_hook(D,F,P)
35580 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
35590 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20 20 20  rns the P.**    
355a0 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20 66        argument f
355b0 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
355c0 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73   call with the s
355d0 61 6d 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ame .**         
355e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
355f0 63 74 69 6f 6e 20 5d 20 44 20 2c 20 6f 72 20 4e  ction ] D , or N
35600 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ULL on the first
35610 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20   call.**        
35620 20 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c    for a particul
35630 61 72 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ar [database con
35640 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
35650 2a 20 7b 46 31 32 39 35 33 7d 20 45 61 63 68 20  * {F12953} Each 
35660 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
35670 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20  _commit_hook()] 
35680 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20 63  overwrites the c
35690 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
356a0 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 62      registered b
356b0 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a  y prior calls..*
356c0 2a 0a 2a 2a 20 7b 46 31 32 39 35 34 7d 20 49 66  *.** {F12954} If
356d0 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20   the F argument 
356e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  to [sqlite3_comm
356f0 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  it_hook(D,F,P)] 
35700 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20  is NULL.**      
35710 20 20 20 20 74 68 65 6e 20 74 68 65 20 63 6f 6d      then the com
35720 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  mit hook callbac
35730 6b 20 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e  k is canceled an
35740 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  d no callback.**
35750 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76            is inv
35760 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e  oked when a tran
35770 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e  saction commits.
35780 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 35 7d 20  .**.** {F12955} 
35790 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 63 61  If the commit ca
357a0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
357b0 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68 65  on-zero then the
357c0 20 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20   commit is.**   
357d0 20 20 20 20 20 20 20 63 6f 6e 76 65 72 74 65 64         converted
357e0 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b   into a rollback
357f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 31 7d  ..**.** {F12961}
35800 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f   The [sqlite3_ro
35810 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c  llback_hook(D,F,
35820 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  P)] interface re
35830 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20  gisters the.**  
35840 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
35850 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62   function F to b
35860 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  e invoked with a
35870 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76  rgument P whenev
35880 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  er.**          a
35890 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c   transaction rol
358a0 6c 73 20 62 61 63 6b 20 6f 6e 20 5b 64 61 74 61  ls back on [data
358b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
358c0 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36   D..**.** {F1296
358d0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
358e0 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c  rollback_hook(D,
358f0 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
35900 72 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a  returns the P.**
35910 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65            argume
35920 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76  nt from the prev
35930 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74  ious call with t
35940 68 65 20 73 61 6d 65 20 0a 2a 2a 20 20 20 20 20  he same .**     
35950 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
35960 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20 44 20 2c 20  onnection ] D , 
35970 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66  or NULL on the f
35980 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20  irst call.**    
35990 20 20 20 20 20 20 66 6f 72 20 61 20 70 61 72 74        for a part
359a0 69 63 75 6c 61 72 20 5b 64 61 74 61 62 61 73 65  icular [database
359b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
359c0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 33 7d 20 45  **.** {F12963} E
359d0 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
359e0 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
359f0 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73  ok()] overwrites
35a00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
35a10 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
35a20 65 72 65 64 20 62 79 20 70 72 69 6f 72 20 63 61  ered by prior ca
35a30 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  lls..**.** {F129
35a40 36 34 7d 20 49 66 20 74 68 65 20 46 20 61 72 67  64} If the F arg
35a50 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
35a60 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
35a70 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a  D,F,P)] is NULL.
35a80 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
35a90 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f   the rollback ho
35aa0 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63  ok callback is c
35ab0 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63  anceled and no c
35ac0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
35ad0 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77      is invoked w
35ae0 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f  hen a transactio
35af0 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f  n rolls back..*/
35b00 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63  .void *sqlite3_c
35b10 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74  ommit_hook(sqlit
35b20 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
35b30 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64  *), void*);.void
35b40 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   *sqlite3_rollba
35b50 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  ck_hook(sqlite3*
35b60 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a  , void(*)(void *
35b70 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
35b80 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
35b90 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61   Change Notifica
35ba0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b  tion Callbacks {
35bb0 46 31 32 39 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12970}.**.** Th
35bc0 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
35bd0 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
35be0 65 0a 2a 2a 20 72 65 67 69 73 74 65 72 73 20 61  e.** registers a
35bf0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
35c00 6f 6e 20 77 69 74 68 20 74 68 65 20 64 61 74 61  on with the data
35c10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
35c20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
35c30 65 20 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75  e .** first argu
35c40 6d 65 6e 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b  ment to be invok
35c50 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
35c60 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
35c70 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
35c80 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61  d..** Any callba
35c90 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
35ca0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
35cb0 73 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74  s function for t
35cc0 68 65 20 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61  he same .** data
35cd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
35ce0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
35cf0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
35d00 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
35d10 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e  inter to the fun
35d20 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20  ction to invoke 
35d30 77 68 65 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69  when a .** row i
35d40 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
35d50 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 20  ted or deleted. 
35d60 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
35d70 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
35d80 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 61 20 63  llback is.** a c
35d90 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
35da0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
35db0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
35dc0 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
35dd0 64 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 61  d callback .** a
35de0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
35df0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  f [SQLITE_INSERT
35e00 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  ], [SQLITE_DELET
35e10 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50  E] or [SQLITE_UP
35e20 44 41 54 45 5d 2c 0a 2a 2a 20 64 65 70 65 6e 64  DATE],.** depend
35e30 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61  ing on the opera
35e40 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64  tion that caused
35e50 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f   the callback to
35e60 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20   be invoked..** 
35e70 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 0a 2a  The third and .*
35e80 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  * fourth argumen
35e90 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ts to the callba
35ea0 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74  ck contain point
35eb0 65 72 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  ers to the datab
35ec0 61 73 65 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c  ase and .** tabl
35ed0 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e  e name containin
35ee0 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72  g the affected r
35ef0 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c  ow..** The final
35f00 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65   callback parame
35f10 74 65 72 20 69 73 20 0a 2a 2a 20 74 68 65 20 72  ter is .** the r
35f20 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 2e  owid of the row.
35f30 0a 2a 2a 20 49 6e 20 74 68 65 20 63 61 73 65 20  .** In the case 
35f40 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68  of an update, th
35f50 69 73 20 69 73 20 74 68 65 20 72 6f 77 69 64 20  is is the rowid 
35f60 61 66 74 65 72 20 0a 2a 2a 20 74 68 65 20 75 70  after .** the up
35f70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65  date takes place
35f80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61  ..**.** The upda
35f90 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69  te hook is not i
35fa0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65  nvoked when inte
35fb0 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c  rnal system tabl
35fc0 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69  es are.** modifi
35fd0 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f  ed (i.e. sqlite_
35fe0 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74  master and sqlit
35ff0 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a  e_sequence)..**.
36000 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75  ** If another fu
36010 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69  nction was previ
36020 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64  ously registered
36030 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c 75 65  , its pArg value
36040 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e  .** is returned.
36050 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c    Otherwise NULL
36060 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
36070 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
36080 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 31 7d 20 54  **.** {F12971} T
36090 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  he [sqlite3_upda
360a0 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  te_hook(D,F,P)] 
360b0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
360c0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
360d0 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46        function F
360e0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
360f0 69 74 68 20 66 69 72 73 74 20 70 61 72 61 6d 65  ith first parame
36100 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ter P whenever.*
36110 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 61 62  *          a tab
36120 6c 65 20 72 6f 77 20 69 73 20 6d 6f 64 69 66 69  le row is modifi
36130 65 64 2c 20 69 6e 73 65 72 74 65 64 2c 20 6f 72  ed, inserted, or
36140 20 64 65 6c 65 74 65 64 20 6f 6e 0a 2a 2a 20 20   deleted on.**  
36150 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
36160 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
36170 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 33 7d 20  .**.** {F12973} 
36180 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64  The [sqlite3_upd
36190 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  ate_hook(D,F,P)]
361a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
361b0 6e 73 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  ns the value.** 
361c0 20 20 20 20 20 20 20 20 20 6f 66 20 50 20 66 6f           of P fo
361d0 72 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  r the previous c
361e0 61 6c 6c 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  all on the same 
361f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36200 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20  tion] D,.**     
36210 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 66 6f 72       or NULL for
36220 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 2e   the first call.
36230 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 35 7d 20  .**.** {F12975} 
36240 49 66 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  If the update ho
36250 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 46 20 69 6e  ok callback F in
36260 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
36270 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a  _hook(D,F,P)].**
36280 20 20 20 20 20 20 20 20 20 20 69 73 20 4e 55 4c            is NUL
36290 4c 20 74 68 65 6e 20 74 68 65 20 6e 6f 20 75 70  L then the no up
362a0 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 73 20 61  date callbacks a
362b0 72 65 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b  re made..**.** {
362c0 46 31 32 39 37 37 7d 20 45 61 63 68 20 63 61 6c  F12977} Each cal
362d0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 75 70  l to [sqlite3_up
362e0 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  date_hook(D,F,P)
362f0 5d 20 6f 76 65 72 72 69 64 65 73 20 70 72 69 6f  ] overrides prio
36300 72 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20  r calls.**      
36310 20 20 20 20 74 6f 20 74 68 65 20 73 61 6d 65 20      to the same 
36320 69 6e 74 65 72 66 61 63 65 20 6f 6e 20 74 68 65  interface on the
36330 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
36340 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
36350 2a 0a 2a 2a 20 7b 46 31 32 39 37 39 7d 20 54 68  *.** {F12979} Th
36360 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61  e update hook ca
36370 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
36380 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72  voked when inter
36390 6e 61 6c 20 73 79 73 74 65 6d 0a 2a 2a 20 20 20  nal system.**   
363a0 20 20 20 20 20 20 20 74 61 62 6c 65 73 20 73 75         tables su
363b0 63 68 20 61 73 20 73 71 6c 69 74 65 5f 6d 61 73  ch as sqlite_mas
363c0 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
363d0 65 71 75 65 6e 63 65 20 61 72 65 20 6d 6f 64 69  equence are modi
363e0 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  fied..**.** {F12
363f0 39 38 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  981} The second 
36400 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
36410 20 75 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b   update callback
36420 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73   .**          is
36430 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
36440 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45  INSERT], [SQLITE
36450 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c  _DELETE] or [SQL
36460 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ITE_UPDATE],.** 
36470 20 20 20 20 20 20 20 20 20 64 65 70 65 6e 64 69           dependi
36480 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ng on the operat
36490 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
364a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20  the callback to 
364b0 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  be invoked..**.*
364c0 2a 20 7b 46 31 32 39 38 33 7d 20 54 68 65 20 74  * {F12983} The t
364d0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
364e0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
364f0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
36500 6e 20 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 20 20  n pointers.**   
36510 20 20 20 20 20 20 20 74 6f 20 7a 65 72 6f 2d 74         to zero-t
36520 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
36530 73 74 72 69 6e 67 73 20 77 68 69 63 68 20 61 72  strings which ar
36540 65 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  e the names of t
36550 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  he.**          d
36560 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c  atabase and tabl
36570 65 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  e that is being 
36580 75 70 64 61 74 65 64 2e 0a 0a 2a 2a 20 7b 46 31  updated...** {F1
36590 32 39 38 35 7d 20 54 68 65 20 66 69 6e 61 6c 20  2985} The final 
365a0 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74  callback paramet
365b0 65 72 20 69 73 20 74 68 65 20 72 6f 77 69 64 20  er is the rowid 
365c0 6f 66 20 74 68 65 20 72 6f 77 20 61 66 74 65 72  of the row after
365d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
365e0 20 63 68 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a   change occurs..
365f0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
36600 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20  _update_hook(.  
36610 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
36620 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20  d(*)(void *,int 
36630 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68  ,char const *,ch
36640 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74  ar const *,sqlit
36650 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69  e3_int64),.  voi
36660 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d*.);../*.** CAP
36670 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f  I3REF:  Enable O
36680 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
36690 20 50 61 67 65 72 20 43 61 63 68 65 20 7b 46 31   Pager Cache {F1
366a0 30 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0330}.**.** This
366b0 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
366c0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
366d0 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20   sharing of the 
366e0 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a  database cache.*
366f0 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74  * and schema dat
36700 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74  a structures bet
36710 77 65 65 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  ween connections
36720 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
36730 61 62 61 73 65 2e 0a 2a 2a 20 53 68 61 72 69 6e  abase..** Sharin
36740 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  g is enabled if 
36750 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
36760 74 72 75 65 20 61 6e 64 20 64 69 73 61 62 6c 65  true and disable
36770 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
36780 74 0a 2a 2a 20 69 73 20 66 61 6c 73 65 2e 0a 2a  t.** is false..*
36790 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69  *.** Cache shari
367a0 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
367b0 64 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f  d disabled.** fo
367c0 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63  r an entire proc
367d0 65 73 73 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20  ess. {END} This 
367e0 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f  is a change as o
367f0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
36800 20 33 2e 35 2e 30 2e 0a 2a 2a 20 49 6e 20 70 72   3.5.0..** In pr
36810 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ior versions of 
36820 53 51 4c 69 74 65 2c 20 73 68 61 72 69 6e 67 20  SQLite, sharing 
36830 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f  was.** enabled o
36840 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65  r disabled for e
36850 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72  ach thread separ
36860 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ately..**.** The
36870 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d   cache sharing m
36880 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20  ode set by this 
36890 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74  interface effect
368a0 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  s all subsequent
368b0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  .** calls to [sq
368c0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
368d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
368e0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
368f0 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45  _open16()]..** E
36900 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65  xisting database
36910 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e   connections con
36920 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68  tinue use the sh
36930 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68  aring mode.** th
36940 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74  at was in effect
36950 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65   at the time the
36960 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a  y were opened..*
36970 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62  *.** Virtual tab
36980 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73  les cannot be us
36990 65 64 20 77 69 74 68 20 61 20 73 68 61 72 65 64  ed with a shared
369a0 20 63 61 63 68 65 2e 20 20 20 57 68 65 6e 20 73   cache.   When s
369b0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
369c0 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b  s enabled, the [
369d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
369e0 6f 64 75 6c 65 28 29 5d 20 41 50 49 20 75 73 65  odule()] API use
369f0 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a  d to register.**
36a00 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
36a10 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
36a20 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a  rn an error..**.
36a30 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
36a40 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
36a50 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61  OK] if shared ca
36a60 63 68 65 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c  che was.** enabl
36a70 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73  ed or disabled s
36a80 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e  uccessfully.  An
36a90 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a   [error code].**
36aa0 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68   is returned oth
36ab0 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68  erwise..**.** Sh
36ac0 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
36ad0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
36ae0 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68  t. But this migh
36af0 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66  t change in.** f
36b00 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
36b10 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69  f SQLite.  Appli
36b20 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72  cations that car
36b30 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a  e about shared.*
36b40 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20  * cache setting 
36b50 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78  should set it ex
36b60 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20  plicitly..**.** 
36b70 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a  INVARIANTS:.** .
36b80 2a 2a 20 7b 46 31 30 33 33 31 7d 20 41 20 73 75  ** {F10331} A su
36b90 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
36ba0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
36bb0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
36bc0 63 68 65 28 42 29 5d 0a 2a 2a 20 20 20 20 20 20  che(B)].**      
36bd0 20 20 20 20 77 69 6c 6c 20 65 6e 61 62 6c 65 20      will enable 
36be0 6f 72 20 64 69 73 61 62 6c 65 20 73 68 61 72 65  or disable share
36bf0 64 20 63 61 63 68 65 20 6d 6f 64 65 20 66 6f 72  d cache mode for
36c00 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 6c   any subsequentl
36c10 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 72  y.**          cr
36c20 65 61 74 65 64 20 5b 64 61 74 61 62 61 73 65 20  eated [database 
36c30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 20 74  connection] in t
36c40 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
36c50 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 36 7d 20  .**.** {F10336} 
36c60 57 68 65 6e 20 73 68 61 72 65 64 20 63 61 63 68  When shared cach
36c70 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68  e is enabled, th
36c80 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
36c90 65 5f 6d 6f 64 75 6c 65 28 29 5d 0a 2a 2a 20 20  e_module()].**  
36ca0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
36cb0 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  e will always re
36cc0 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a  turn an error..*
36cd0 2a 0a 2a 2a 20 7b 46 31 30 33 33 37 7d 20 54 68  *.** {F10337} Th
36ce0 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  e [sqlite3_enabl
36cf0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 42  e_shared_cache(B
36d00 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
36d10 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
36d20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20   [SQLITE_OK] if 
36d30 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73  shared cache was
36d40 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
36d50 62 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  bled successfull
36d60 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 39  y..**.** {F10339
36d70 7d 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69  } Shared cache i
36d80 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
36d90 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fault..*/.int sq
36da0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
36db0 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
36dc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36dd0 20 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65    Attempt To Fre
36de0 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 20 7b 46  e Heap Memory {F
36df0 31 37 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  17340}.**.** The
36e00 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
36e10 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66  _memory() interf
36e20 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 0a  ace attempts to.
36e30 2a 2a 20 66 72 65 65 20 4e 20 62 79 74 65 73 20  ** free N bytes 
36e40 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62  of heap memory b
36e50 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e  y deallocating n
36e60 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
36e70 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
36e80 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 64  ns held by the d
36e90 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e  atabase library.
36ea0 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75   {END}  Memory u
36eb0 73 65 64 0a 2a 2a 20 74 6f 20 63 61 63 68 65 20  sed.** to cache 
36ec0 64 61 74 61 62 61 73 65 20 70 61 67 65 73 20 74  database pages t
36ed0 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
36ee0 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
36ef0 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6f 6e 2d 65 73  ple of.** non-es
36f00 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 20  sential memory. 
36f10 20 53 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   Sqlite3_release
36f20 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
36f30 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
36f40 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c  of bytes actuall
36f50 79 20 66 72 65 65 64 2c 20 77 68 69 63 68 20 6d  y freed, which m
36f60 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
36f70 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 74 68 65  less.** than the
36f80 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65   amount requeste
36f90 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
36fa0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  NTS:.**.** {F173
36fb0 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
36fc0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
36fd0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 74  N)] interface at
36fe0 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 20 20 20  tempts to.**    
36ff0 20 20 20 20 20 20 66 72 65 65 20 4e 20 62 79 74        free N byt
37000 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  es of heap memor
37010 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e  y by deallocatin
37020 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a  g non-essential.
37030 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f  **          memo
37040 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68  ry allocations h
37050 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62  eld by the datab
37060 61 73 65 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  ase library..**.
37070 2a 2a 20 7b 46 31 36 33 34 32 7d 20 54 68 65 20  ** {F16342} The 
37080 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
37090 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 72 65 74 75  _memory(N)] retu
370a0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  rns the number.*
370b0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 62 79  *          of by
370c0 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65  tes actually fre
370d0 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20  ed, which might 
370e0 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a  be more or less.
370f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 6e  **          than
37100 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75   the amount requ
37110 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ested..*/.int sq
37120 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
37130 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mory(int);../*.*
37140 2a 20 43 41 50 49 33 52 45 46 3a 20 20 49 6d 70  * CAPI3REF:  Imp
37150 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48  ose A Limit On H
37160 65 61 70 20 53 69 7a 65 20 7b 46 31 37 33 35 30  eap Size {F17350
37170 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
37180 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
37190 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a  mit() interface.
371a0 2a 2a 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66  ** places a "sof
371b0 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  t" limit on the 
371c0 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
371d0 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
371e0 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 62  e allocated.** b
371f0 79 20 53 51 4c 69 74 65 2e 20 49 66 20 61 6e 20  y SQLite. If an 
37200 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74  internal allocat
37210 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
37220 20 0a 2a 2a 20 74 68 61 74 20 77 6f 75 6c 64 20   .** that would 
37230 65 78 63 65 65 64 20 74 68 65 20 73 6f 66 74 20  exceed the soft 
37240 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c  heap limit, [sql
37250 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
37260 6f 72 79 28 29 5d 20 69 73 0a 2a 2a 20 69 6e 76  ory()] is.** inv
37270 6f 6b 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  oked one or more
37280 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75   times to free u
37290 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66  p some space bef
372a0 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69  ore the allocati
372b0 6f 6e 0a 2a 2a 20 69 73 20 6d 61 64 65 2e 0a 2a  on.** is made..*
372c0 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69  *.** The limit i
372d0 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c  s called "soft",
372e0 20 62 65 63 61 75 73 65 20 69 66 0a 2a 2a 20 5b   because if.** [
372f0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
37300 6d 65 6d 6f 72 79 28 29 5d 20 63 61 6e 6e 6f 74  memory()] cannot
37310 0a 2a 2a 20 66 72 65 65 20 73 75 66 66 69 63 69  .** free suffici
37320 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72  ent memory to pr
37330 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20  event the limit 
37340 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65  from being excee
37350 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  ded,.** the memo
37360 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20  ry is allocated 
37370 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63  anyway and the c
37380 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
37390 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a   proceeds..**.**
373a0 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a   A negative or z
373b0 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20  ero value for N 
373c0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65  means that there
373d0 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70   is no soft heap
373e0 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73   limit and.** [s
373f0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
37400 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e  emory()] will on
37410 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
37420 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61  n memory is exha
37430 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65  usted..** The de
37440 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20  fault value for 
37450 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
37460 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  mit is zero..**.
37470 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
37480 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f  a best effort to
37490 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20   honor the soft 
374a0 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 0a 2a 2a  heap limit.  .**
374b0 20 42 75 74 20 69 66 20 74 68 65 20 73 6f 66 74   But if the soft
374c0 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e   heap limit cann
374d0 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65  ot be honored, e
374e0 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  xecution will.**
374f0 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75   continue withou
37500 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66  t error or notif
37510 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 69  ication.  This i
37520 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20  s why the limit 
37530 69 73 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20  is .** called a 
37540 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49  "soft" limit.  I
37550 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e  t is advisory on
37560 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ly..**.** Prior 
37570 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
37580 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f  n 3.5.0, this ro
37590 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74  utine only const
375a0 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72  rained the memor
375b0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62  y.** allocated b
375c0 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
375d0 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72  d - the same thr
375e0 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69  ead in which thi
375f0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e  s routine.** run
37600 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69  s.  Beginning wi
37610 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  th SQLite versio
37620 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66  n 3.5.0, the sof
37630 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a  t heap limit is.
37640 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c  ** applied to al
37650 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20 76  l threads. The v
37660 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 66  alue specified f
37670 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
37680 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20   limit.** is an 
37690 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74  upper bound on t
376a0 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20  he total memory 
376b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61  allocation for a
376c0 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a  ll threads. In.*
376d0 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  * version 3.5.0 
376e0 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68  there is no mech
376f0 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69  anism for limiti
37700 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67  ng the heap usag
37710 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64  e for.** individ
37720 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a  ual threads..**.
37730 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
37740 2a 0a 2a 2a 20 7b 46 31 36 33 35 31 7d 20 54 68  *.** {F16351} Th
37750 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  e [sqlite3_soft_
37760 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 69  heap_limit(N)] i
37770 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65 73 20  nterface places 
37780 61 20 73 6f 66 74 20 6c 69 6d 69 74 0a 2a 2a 20  a soft limit.** 
37790 20 20 20 20 20 20 20 20 20 6f 66 20 4e 20 62 79           of N by
377a0 74 65 73 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e  tes on the amoun
377b0 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  t of heap memory
377c0 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c   that may be all
377d0 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  ocated.**       
377e0 20 20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65     using [sqlite
377f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
37800 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
37810 29 5d 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 0a  )] at any point.
37820 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 74  **          in t
37830 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33  ime..**.** {F163
37840 35 32 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f  52} If a call to
37850 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
37860 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
37870 72 65 61 6c 6c 6f 63 28 29 5d 20 77 6f 75 6c 64  realloc()] would
37880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 75  .**          cau
37890 73 65 20 74 68 65 20 74 6f 74 61 6c 20 61 6d 6f  se the total amo
378a0 75 6e 74 20 6f 66 20 61 6c 6c 6f 63 61 74 65 64  unt of allocated
378b0 20 6d 65 6d 6f 72 79 20 74 6f 20 65 78 63 65 65   memory to excee
378c0 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  d the.**        
378d0 20 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69    soft heap limi
378e0 74 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  t, then [sqlite3
378f0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
37900 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  )] is invoked.**
37910 20 20 20 20 20 20 20 20 20 20 69 6e 20 61 6e 20            in an 
37920 61 74 74 65 6d 70 74 20 74 6f 20 72 65 64 75 63  attempt to reduc
37930 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 75 73 61  e the memory usa
37940 67 65 20 70 72 69 6f 72 20 74 6f 20 70 72 6f 63  ge prior to proc
37950 65 65 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  eeding.**       
37960 20 20 20 77 69 74 68 20 74 68 65 20 6d 65 6d 6f     with the memo
37970 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 74  ry allocation at
37980 74 65 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tempt..**.** {F1
37990 36 33 35 33 7d 20 43 61 6c 6c 73 20 74 6f 20 5b  6353} Calls to [
379a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
379b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
379c0 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 74 72  alloc()] that tr
379d0 69 67 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  igger.**        
379e0 20 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65    attempts to re
379f0 64 75 63 65 20 6d 65 6d 6f 72 79 20 75 73 61 67  duce memory usag
37a00 65 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 6f  e through the so
37a10 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a  ft heap limit.**
37a20 20 20 20 20 20 20 20 20 20 20 6d 65 63 68 61 6e            mechan
37a30 69 73 6d 20 63 6f 6e 74 69 6e 75 65 20 65 76 65  ism continue eve
37a40 6e 20 69 66 20 74 68 65 20 61 74 74 65 6d 70 74  n if the attempt
37a50 20 74 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f 72   to reduce memor
37a60 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73  y.**          us
37a70 61 67 65 20 69 73 20 75 6e 73 75 63 63 65 73 73  age is unsuccess
37a80 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33  ful..**.** {F163
37a90 35 34 7d 20 41 20 6e 65 67 61 74 69 76 65 20 6f  54} A negative o
37aa0 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72  r zero value for
37ab0 20 4e 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a   N in a call to.
37ac0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
37ad0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
37ae0 69 6d 69 74 28 4e 29 5d 20 6d 65 61 6e 73 20 74  imit(N)] means t
37af0 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hat there is no 
37b00 73 6f 66 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  soft.**         
37b10 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 20   heap limit and 
37b20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
37b30 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20  _memory()] will 
37b40 6f 6e 6c 79 20 62 65 0a 2a 2a 20 20 20 20 20 20  only be.**      
37b50 20 20 20 20 63 61 6c 6c 65 64 20 77 68 65 6e 20      called when 
37b60 6d 65 6d 6f 72 79 20 69 73 20 63 6f 6d 70 6c 65  memory is comple
37b70 74 65 6c 79 20 65 78 68 61 75 73 74 65 64 2e 0a  tely exhausted..
37b80 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 35 7d 20 54  **.** {F16355} T
37b90 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
37ba0 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
37bb0 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f  ap limit is zero
37bc0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 38 7d  ..**.** {F16358}
37bd0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73   Each call to [s
37be0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
37bf0 5f 6c 69 6d 69 74 28 4e 29 5d 20 6f 76 65 72 72  _limit(N)] overr
37c00 69 64 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ides the.**     
37c10 20 20 20 20 20 76 61 6c 75 65 73 20 73 65 74 20       values set 
37c20 62 79 20 61 6c 6c 20 70 72 69 6f 72 20 63 61 6c  by all prior cal
37c30 6c 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ls..*/.void sqli
37c40 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
37c50 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mit(int);../*.**
37c60 20 43 41 50 49 33 52 45 46 3a 20 20 45 78 74 72   CAPI3REF:  Extr
37c70 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f  act Metadata Abo
37c80 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41  ut A Column Of A
37c90 20 54 61 62 6c 65 20 7b 46 31 32 38 35 30 7d 0a   Table {F12850}.
37ca0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
37cb0 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6d 65  ne.** returns me
37cc0 74 61 2d 64 61 74 61 20 61 62 6f 75 74 20 61 20  ta-data about a 
37cd0 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20  specific column 
37ce0 6f 66 20 61 20 73 70 65 63 69 66 69 63 20 64 61  of a specific da
37cf0 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 20  tabase.** table 
37d00 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67  accessible using
37d10 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
37d20 68 61 6e 64 6c 65 20 70 61 73 73 65 64 20 61 73  handle passed as
37d30 20 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74   the first funct
37d40 69 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ion .** argument
37d50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75  ..**.** The colu
37d60 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64  mn is identified
37d70 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20   by the second, 
37d80 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
37d90 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 0a   parameters to .
37da0 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
37db0 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
37dc0 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 72  ameter is either
37dd0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
37de0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e   database.** (i.
37df0 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e. "main", "temp
37e00 22 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64  " or an attached
37e10 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61   database) conta
37e20 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 66  ining the specif
37e30 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20  ied.** table or 
37e40 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 4e  NULL. If it is N
37e50 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74  ULL, then all at
37e60 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
37e70 20 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a   are searched.**
37e80 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75   for the table u
37e90 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
37ea0 67 6f 72 69 74 68 6d 20 61 73 20 74 68 65 20 64  gorithm as the d
37eb0 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 75  atabase engine u
37ec0 73 65 73 20 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c  ses to .** resol
37ed0 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74  ve unqualified t
37ee0 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e  able references.
37ef0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  .**.** The third
37f00 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
37f10 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66  meters to this f
37f20 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20  unction are the 
37f30 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
37f40 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65   .** name of the
37f50 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c   desired column,
37f60 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e   respectively. N
37f70 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
37f80 70 61 72 61 6d 65 74 65 72 73 20 0a 2a 2a 20 6d  parameters .** m
37f90 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ay be NULL..**.*
37fa0 2a 20 4d 65 74 61 20 69 6e 66 6f 72 6d 61 74 69  * Meta informati
37fb0 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  on is returned b
37fc0 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65  y writing to the
37fd0 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e   memory location
37fe0 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74  s passed as.** t
37ff0 68 65 20 35 74 68 20 61 6e 64 20 73 75 62 73 65  he 5th and subse
38000 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73  quent parameters
38010 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
38020 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 73 65 20  n. Any of these 
38030 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6d 61  .** arguments ma
38040 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68  y be NULL, in wh
38050 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72  ich case the cor
38060 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65  responding eleme
38070 6e 74 20 6f 66 20 6d 65 74 61 20 0a 2a 2a 20 69  nt of meta .** i
38080 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6f 6d  nformation is om
38090 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72  itted..**.** <pr
380a0 65 3e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 20  e>.** Parameter 
380b0 20 20 20 20 4f 75 74 70 75 74 20 54 79 70 65 20      Output Type 
380c0 20 20 20 20 20 44 65 73 63 72 69 70 74 69 6f 6e       Description
380d0 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  .** ------------
380e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
380f0 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20  -------.**.**   
38100 35 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73  5th         cons
38110 74 20 63 68 61 72 2a 20 20 20 20 20 20 44 61 74  t char*      Dat
38120 61 20 74 79 70 65 0a 2a 2a 20 20 20 36 74 68 20  a type.**   6th 
38130 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68          const ch
38140 61 72 2a 20 20 20 20 20 20 4e 61 6d 65 20 6f 66  ar*      Name of
38150 20 74 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6c   the default col
38160 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
38170 0a 2a 2a 20 20 20 37 74 68 20 20 20 20 20 20 20  .**   7th       
38180 20 20 69 6e 74 20 20 20 20 20 20 20 20 20 20 20    int           
38190 20 20 20 54 72 75 65 20 69 66 20 74 68 65 20 63     True if the c
381a0 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20  olumn has a NOT 
381b0 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a  NULL constraint.
381c0 2a 2a 20 20 20 38 74 68 20 20 20 20 20 20 20 20  **   8th        
381d0 20 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20   int            
381e0 20 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f    True if the co
381f0 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20  lumn is part of 
38200 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a  the PRIMARY KEY.
38210 2a 2a 20 20 20 39 74 68 20 20 20 20 20 20 20 20  **   9th        
38220 20 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20   int            
38230 20 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f    True if the co
38240 6c 75 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43 52  lumn is AUTOINCR
38250 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a  EMENT.** </pre>.
38260 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d  **.**.** The mem
38270 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ory pointed to b
38280 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20  y the character 
38290 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
382a0 64 20 66 6f 72 20 74 68 65 20 0a 2a 2a 20 64 65  d for the .** de
382b0 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61  claration type a
382c0 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  nd collation seq
382d0 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f  uence is valid o
382e0 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  nly until the ne
382f0 78 74 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61  xt .** call to a
38300 6e 79 20 73 71 6c 69 74 65 20 41 50 49 20 66 75  ny sqlite API fu
38310 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  nction..**.** If
38320 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74   the specified t
38330 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79  able is actually
38340 20 61 20 76 69 65 77 2c 20 74 68 65 6e 20 61 6e   a view, then an
38350 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
38360 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
38370 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d   specified colum
38380 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f  n is "rowid", "o
38390 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22  id" or "_rowid_"
383a0 20 61 6e 64 20 61 6e 20 0a 2a 2a 20 49 4e 54 45   and an .** INTE
383b0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20  GER PRIMARY KEY 
383c0 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20  column has been 
383d0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
383e0 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  red, then the ou
383f0 74 70 75 74 20 0a 2a 2a 20 70 61 72 61 6d 65 74  tput .** paramet
38400 65 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20  ers are set for 
38410 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64  the explicitly d
38420 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20  eclared column. 
38430 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a  If there is no.*
38440 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  * explicitly dec
38450 6c 61 72 65 64 20 49 50 4b 20 63 6f 6c 75 6d 6e  lared IPK column
38460 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75  , then the outpu
38470 74 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  t parameters are
38480 20 73 65 74 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c   set as .** foll
38490 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e  ows:.**.** <pre>
384a0 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70  .**     data typ
384b0 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20  e: "INTEGER".** 
384c0 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65      collation se
384d0 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22  quence: "BINARY"
384e0 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c  .**     not null
384f0 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61  : 0.**     prima
38500 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20  ry key: 1.**    
38510 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a   auto increment:
38520 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a   0.** </pre>.**.
38530 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
38540 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72   may load one or
38550 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72   more schemas fr
38560 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  om database file
38570 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f  s. If an.** erro
38580 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
38590 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72  this process, or
385a0 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65   if the requeste
385b0 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  d table or colum
385c0 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66  n.** cannot be f
385d0 6f 75 6e 64 2c 20 61 6e 20 53 51 4c 49 54 45 20  ound, an SQLITE 
385e0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
385f0 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72  turned and an er
38600 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 6c  ror message.** l
38610 65 66 74 20 69 6e 20 74 68 65 20 64 61 74 61 62  eft in the datab
38620 61 73 65 20 68 61 6e 64 6c 65 20 28 74 6f 20 62  ase handle (to b
38630 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e  e retrieved usin
38640 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  g sqlite3_errmsg
38650 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ())..**.** This 
38660 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  API is only avai
38670 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
38680 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
38690 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
386a0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
386b0 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70  MN_METADATA prep
386c0 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20  rocessor symbol 
386d0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  defined..*/.int 
386e0 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f  sqlite3_table_co
386f0 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20  lumn_metadata(. 
38700 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
38710 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
38720 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c  Connection handl
38730 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
38740 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20  r *zDbName,     
38750 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e     /* Database n
38760 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20  ame or NULL */. 
38770 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61   const char *zTa
38780 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20  bleName,     /* 
38790 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  Table name */.  
387a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c  const char *zCol
387b0 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43  umnName,    /* C
387c0 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20  olumn name */.  
387d0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44  char const **pzD
387e0 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f  ataType,    /* O
387f0 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20  UTPUT: Declared 
38800 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63  data type */.  c
38810 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f  har const **pzCo
38820 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55  llSeq,     /* OU
38830 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  TPUT: Collation 
38840 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f  sequence name */
38850 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c  .  int *pNotNull
38860 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
38870 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
38880 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74  f NOT NULL const
38890 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a  raint exists */.
388a0 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b    int *pPrimaryK
388b0 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ey,           /*
388c0 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
388d0 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20   column part of 
388e0 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75  PK */.  int *pAu
388f0 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20  toinc           
38900 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
38910 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73  rue if column is
38920 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20   auto-increment 
38930 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
38940 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45  I3REF: Load An E
38950 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32 36 30 30  xtension {F12600
38960 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 31 7d  }.**.** {F12601}
38970 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61   The sqlite3_loa
38980 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
38990 74 65 72 66 61 63 65 0a