/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact 30a57188b126a001dbc28955885fb9698a3b02e9:


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 37 38 20 32 30 30 38 2f 30  n,v 1.378 2008/0
05f0: 37 2f 32 34 20 30 38 3a 32 30 3a 34 30 20 64 61  7/24 08:20:40 da
0600: 6e 69 65 6c 6b 31 39 37 37 20 45 78 70 20 24 0a  nielk1977 Exp $.
0610: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
0620: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
0630: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0640: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0650: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0660: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0670: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0680: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0690: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
06a0: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
06b0: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
06c0: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
06d0: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06e0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06f0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
0700: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
0710: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
0720: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
0730: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0740: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75  ndif../*.** Ensu
0750: 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73  re these symbols
0760: 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65   were not define
0770: 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f  d by some previo
0780: 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a  us header file..
0790: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
07a0: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66  _VERSION.# undef
07b0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
07c0: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51  #endif.#ifdef SQ
07d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
07e0: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  BER.# undef SQLI
07f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0800: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  R.#endif../*.** 
0810: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
0820: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  e-Time Library V
0830: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b  ersion Numbers {
0840: 48 31 30 30 31 30 7d 20 3c 53 36 30 31 30 30 3e  H10010} <S60100>
0850: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
0860: 45 5f 56 45 52 53 49 4f 4e 20 61 6e 64 20 53 51  E_VERSION and SQ
0870: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
0880: 42 45 52 20 23 64 65 66 69 6e 65 73 20 69 6e 0a  BER #defines in.
0890: 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68  ** the sqlite3.h
08a0: 20 66 69 6c 65 20 73 70 65 63 69 66 79 20 74 68   file specify th
08b0: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  e version of SQL
08c0: 69 74 65 20 77 69 74 68 20 77 68 69 63 68 0a 2a  ite with which.*
08d0: 2a 20 74 68 61 74 20 68 65 61 64 65 72 20 66 69  * that header fi
08e0: 6c 65 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  le is associated
08f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 76 65 72  ..**.** The "ver
0900: 73 69 6f 6e 22 20 6f 66 20 53 51 4c 69 74 65 20  sion" of SQLite 
0910: 69 73 20 61 20 73 74 72 69 6e 67 20 6f 66 20 74  is a string of t
0920: 68 65 20 66 6f 72 6d 20 22 58 2e 59 2e 5a 22 2e  he form "X.Y.Z".
0930: 0a 2a 2a 20 54 68 65 20 70 68 72 61 73 65 20 22  .** The phrase "
0940: 61 6c 70 68 61 22 20 6f 72 20 22 62 65 74 61 22  alpha" or "beta"
0950: 20 6d 69 67 68 74 20 62 65 20 61 70 70 65 6e 64   might be append
0960: 65 64 20 61 66 74 65 72 20 74 68 65 20 5a 2e 0a  ed after the Z..
0970: 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 69  ** The X value i
0980: 73 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20  s major version 
0990: 6e 75 6d 62 65 72 20 61 6c 77 61 79 73 20 33 20  number always 3 
09a0: 69 6e 20 53 51 4c 69 74 65 33 2e 0a 2a 2a 20 54  in SQLite3..** T
09b0: 68 65 20 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20  he X value only 
09c0: 63 68 61 6e 67 65 73 20 77 68 65 6e 20 62 61 63  changes when bac
09d0: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
09e0: 6c 69 74 79 20 69 73 0a 2a 2a 20 62 72 6f 6b 65  lity is.** broke
09f0: 6e 20 61 6e 64 20 77 65 20 69 6e 74 65 6e 64 20  n and we intend 
0a00: 74 6f 20 6e 65 76 65 72 20 62 72 65 61 6b 20 62  to never break b
0a10: 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
0a20: 62 69 6c 69 74 79 2e 0a 2a 2a 20 54 68 65 20 59  bility..** The Y
0a30: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6d 69   value is the mi
0a40: 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  nor version numb
0a50: 65 72 20 61 6e 64 20 6f 6e 6c 79 20 63 68 61 6e  er and only chan
0a60: 67 65 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 72  ges when.** ther
0a70: 65 20 61 72 65 20 6d 61 6a 6f 72 20 66 65 61 74  e are major feat
0a80: 75 72 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73  ure enhancements
0a90: 20 74 68 61 74 20 61 72 65 20 66 6f 72 77 61 72   that are forwar
0aa0: 64 73 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a  ds compatible.**
0ab0: 20 62 75 74 20 6e 6f 74 20 62 61 63 6b 77 61 72   but not backwar
0ac0: 64 73 20 63 6f 6d 70 61 74 69 62 6c 65 2e 0a 2a  ds compatible..*
0ad0: 2a 20 54 68 65 20 5a 20 76 61 6c 75 65 20 69 73  * The Z value is
0ae0: 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d   the release num
0af0: 62 65 72 20 61 6e 64 20 69 73 20 69 6e 63 72 65  ber and is incre
0b00: 6d 65 6e 74 65 64 20 77 69 74 68 0a 2a 2a 20 65  mented with.** e
0b10: 61 63 68 20 72 65 6c 65 61 73 65 20 62 75 74 20  ach release but 
0b20: 72 65 73 65 74 73 20 62 61 63 6b 20 74 6f 20 30  resets back to 0
0b30: 20 77 68 65 6e 65 76 65 72 20 59 20 69 73 20 69   whenever Y is i
0b40: 6e 63 72 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a  ncremented..**.*
0b50: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0b60: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0b70: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
0b80: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0b90: 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  r()]..**.** INVA
0ba0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
0bb0: 31 30 30 31 31 7d 20 54 68 65 20 53 51 4c 49 54  10011} The SQLIT
0bc0: 45 5f 56 45 52 53 49 4f 4e 20 23 64 65 66 69 6e  E_VERSION #defin
0bd0: 65 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  e in the sqlite3
0be0: 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 20 73  .h header file s
0bf0: 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
0c00: 20 65 76 61 6c 75 61 74 65 20 74 6f 20 61 20 73   evaluate to a s
0c10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0c20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0c30: 20 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 20 20 20   version.**     
0c40: 20 20 20 20 20 77 69 74 68 20 77 68 69 63 68 20       with which 
0c50: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20  the header file 
0c60: 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a  is associated..*
0c70: 2a 0a 2a 2a 20 7b 48 31 30 30 31 34 7d 20 54 68  *.** {H10014} Th
0c80: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0c90: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 20  _NUMBER #define 
0ca0: 73 68 61 6c 6c 20 72 65 73 6f 6c 76 65 20 74 6f  shall resolve to
0cb0: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20   an integer.**  
0cc0: 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65          with the
0cd0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0ce0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0cf0: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d00: 5a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  Z.**          ar
0d10: 65 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73  e the major vers
0d20: 69 6f 6e 2c 20 6d 69 6e 6f 72 20 76 65 72 73 69  ion, minor versi
0d30: 6f 6e 2c 20 61 6e 64 20 72 65 6c 65 61 73 65 20  on, and release 
0d40: 6e 75 6d 62 65 72 2e 0a 2a 2f 0a 23 64 65 66 69  number..*/.#defi
0d50: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
0d60: 4e 20 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52  N         "--VER
0d70: 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c  S--".#define SQL
0d80: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d90: 45 52 20 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55  ER  --VERSION-NU
0da0: 4d 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41  MBER--../*.** CA
0db0: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
0dc0: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
0dd0: 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 32 30   Numbers {H10020
0de0: 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45  } <S60100>.** KE
0df0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
0e00: 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  version.**.** Th
0e10: 65 73 65 20 66 65 61 74 75 72 65 73 20 70 72 6f  ese features pro
0e20: 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e  vide the same in
0e30: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65  formation as the
0e40: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0e50: 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45  ].** and [SQLITE
0e60: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
0e70: 20 23 64 65 66 69 6e 65 73 20 69 6e 20 74 68 65   #defines in the
0e80: 20 68 65 61 64 65 72 2c 20 62 75 74 20 61 72 65   header, but are
0e90: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
0ea0: 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20  ith the library 
0eb0: 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68  instead of the h
0ec0: 65 61 64 65 72 20 66 69 6c 65 2e 20 20 43 61 75  eader file.  Cau
0ed0: 74 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d 65 72  tious programmer
0ee0: 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75  s might.** inclu
0ef0: 64 65 20 61 20 63 68 65 63 6b 20 69 6e 20 74 68  de a check in th
0f00: 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  eir application 
0f10: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 0a 2a  to verify that.*
0f20: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
0f30: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c  sion_number() al
0f40: 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
0f50: 20 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54   value.** [SQLIT
0f60: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0f70: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ]..**.** The sql
0f80: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f90: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
0fa0: 6e 73 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  ns the same info
0fb0: 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a  rmation as is.**
0fc0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
0fd0: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
0fe0: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
0ff0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76  function is prov
1000: 69 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20  ided.** for use 
1010: 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c  in DLLs since DL
1020: 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20  L users usually 
1030: 64 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 72 65  do not have dire
1040: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72  ct access to str
1050: 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73  ing.** constants
1060: 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e   within the DLL.
1070: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1080: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 31  S:.**.** {H10021
1090: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  } The [sqlite3_l
10a0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
10b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  ()] interface sh
10c0: 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  all return.**   
10d0: 20 20 20 20 20 20 20 61 6e 20 69 6e 74 65 67 65         an intege
10e0: 72 20 65 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49  r equal to [SQLI
10f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1100: 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32  R]..**.** {H1002
1110: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
1120: 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20  version] string 
1130: 63 6f 6e 73 74 61 6e 74 20 73 68 61 6c 6c 20 63  constant shall c
1140: 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20  ontain.**       
1150: 20 20 20 74 68 65 20 74 65 78 74 20 6f 66 20 74     the text of t
1160: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1170: 4f 4e 5d 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ON] string..**.*
1180: 2a 20 7b 48 31 30 30 32 33 7d 20 54 68 65 20 5b  * {H10023} The [
1190: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
11a0: 6f 6e 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73  on()] function s
11b0: 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20  hall return.**  
11c0: 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65          a pointe
11d0: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
11e0: 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e  3_version] strin
11f0: 67 20 63 6f 6e 73 74 61 6e 74 2e 0a 2a 2f 0a 53  g constant..*/.S
1200: 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e  QLITE_EXTERN con
1210: 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f  st char sqlite3_
1220: 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74  version[];.const
1230: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c   char *sqlite3_l
1240: 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b  ibversion(void);
1250: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62  .int sqlite3_lib
1260: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
1270: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
1280: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1290: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
12a0: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 20  y Is Threadsafe 
12b0: 7b 48 31 30 31 30 30 7d 20 3c 53 36 30 31 30 30  {H10100} <S60100
12c0: 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  >.**.** SQLite c
12d0: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77  an be compiled w
12e0: 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d  ith or without m
12f0: 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a  utexes.  When.**
1300: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1310: 45 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72  EADSAFE] C prepr
1320: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73  ocessor macro is
1330: 20 74 72 75 65 2c 20 6d 75 74 65 78 65 73 0a 2a   true, mutexes.*
1340: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1350: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1360: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1370: 61 74 20 6d 61 63 72 6f 20 69 73 20 66 61 6c 73  at macro is fals
1380: 65 2c 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  e,.** the mutexe
1390: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
13a0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
13b0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
13c0: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
13d0: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
13e0: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
13f0: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1400: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1410: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1420: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1430: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1440: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1450: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1460: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1470: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1480: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1490: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
14a0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
14b0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
14c0: 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  d..** The defaul
14d0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
14e0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
14f0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
1500: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
1510: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 20 70  n be used by a p
1520: 72 6f 67 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73  rogram to make s
1530: 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
1540: 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
1550: 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e  e that it is lin
1560: 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73  king against was
1570: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
1580: 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65  * the desired se
1590: 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51  tting of the [SQ
15a0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
15b0: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68   macro..**.** Th
15c0: 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c  is interface onl
15d0: 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65  y reports on the
15e0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75   compile-time mu
15f0: 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f  tex setting.** o
1600: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1610: 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20  READSAFE] flag. 
1620: 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
1630: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53  mpiled with.** S
1640: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1650: 3d 31 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =1 then mutexes 
1660: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
1670: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
1680: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
1690: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
16a0: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
16b0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
16c0: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
16d0: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
16e0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
16f0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
1700: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
1710: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
1720: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54  ONFIG_MUTEX].  T
1730: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1740: 6f 66 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  of this function
1750: 20 73 68 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74   shows.** only t
1760: 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6d 70 69  he default compi
1770: 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 2c  le-time setting,
1780: 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d   not any run-tim
1790: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
17a0: 74 68 61 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  that setting..**
17b0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
17c0: 2a 2a 0a 2a 2a 20 7b 48 31 30 31 30 31 7d 20 54  **.** {H10101} T
17d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  he [sqlite3_thre
17e0: 61 64 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69  adsafe()] functi
17f0: 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  on shall return 
1800: 6e 6f 6e 7a 65 72 6f 20 69 66 0a 2a 2a 20 20 20  nonzero if.**   
1810: 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 77 61         SQLite wa
1820: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1830: 74 68 65 20 69 74 73 20 6d 75 74 65 78 65 73 20  the its mutexes 
1840: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
1850: 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  lt.**          o
1860: 72 20 7a 65 72 6f 20 69 66 20 53 51 4c 69 74 65  r zero if SQLite
1870: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 73 75   was compiled su
1880: 63 68 20 74 68 61 74 20 6d 75 74 65 78 65 73 20  ch that mutexes 
1890: 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  are.**          
18a0: 70 65 72 6d 61 6e 65 6e 74 6c 79 20 64 69 73 61  permanently disa
18b0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  bled..**.** {H10
18c0: 31 30 32 7d 20 54 68 65 20 76 61 6c 75 65 20 72  102} The value r
18d0: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 5b  eturned by the [
18e0: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
18f0: 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  fe()] function.*
1900: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
1910: 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 65 6e   not change when
1920: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 20 61   mutex setting a
1930: 72 65 20 6d 6f 64 69 66 69 65 64 20 61 74 0a 2a  re modified at.*
1940: 2a 20 20 20 20 20 20 20 20 20 20 72 75 6e 74 69  *          runti
1950: 6d 65 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  me using the [sq
1960: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
1970: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 0a 2a  interface and .*
1980: 2a 20 20 20 20 20 20 20 20 20 20 65 73 70 65 63  *          espec
1990: 69 61 6c 6c 79 20 74 68 65 20 5b 53 51 4c 49 54  ially the [SQLIT
19a0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
19b0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 20 20 20 20 20  HREAD],.**      
19c0: 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46      [SQLITE_CONF
19d0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
19e0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
19f0: 53 45 52 49 41 4c 49 5a 45 44 5d 2c 0a 2a 2a 20  SERIALIZED],.** 
1a00: 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b 53 51           and [SQ
1a10: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
1a20: 58 5d 20 76 65 72 62 73 2e 0a 2a 2f 0a 69 6e 74  X] verbs..*/.int
1a30: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
1a40: 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  afe(void);../*.*
1a50: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
1a60: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
1a70: 48 61 6e 64 6c 65 20 7b 48 31 32 30 30 30 7d 20  Handle {H12000} 
1a80: 3c 53 34 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S40200>.** KEYW
1a90: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
1aa0: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
1ab0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ac0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
1ad0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
1ae0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
1af0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
1b00: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
1b10: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
1b20: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
1b30: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
1b40: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
1b50: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
1b60: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
1b70: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
1b80: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1b90: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1ba0: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
1bb0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
1bc0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
1bd0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
1be0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
1bf0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
1c00: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
1c10: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
1c20: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
1c30: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
1c40: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
1c50: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
1c60: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
1c70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
1c80: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
1c90: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
1ca0: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
1cb0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
1cc0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
1cd0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
1ce0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
1cf0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
1d00: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
1d10: 65 73 20 7b 48 31 30 32 30 30 7d 20 3c 53 31 30  es {H10200} <S10
1d20: 31 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  110>.** KEYWORDS
1d30: 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  : sqlite_int64 s
1d40: 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a  qlite_uint64.**.
1d50: 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65  ** Because there
1d60: 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61   is no cross-pla
1d70: 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65  tform way to spe
1d80: 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65  cify 64-bit inte
1d90: 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c  ger types.** SQL
1da0: 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70  ite includes typ
1db0: 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74  edefs for 64-bit
1dc0: 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69   signed and unsi
1dd0: 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a  gned integers..*
1de0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1df0: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
1e00: 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68  e3_uint64 are th
1e10: 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65  e preferred type
1e20: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a   definitions..**
1e30: 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36   The sqlite_int6
1e40: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
1e50: 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75  t64 types are su
1e60: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b  pported for back
1e70: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69  wards.** compati
1e80: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  bility only..**.
1e90: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1ea0: 2a 0a 2a 2a 20 7b 48 31 30 32 30 31 7d 20 54 68  *.** {H10201} Th
1eb0: 65 20 5b 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d  e [sqlite_int64]
1ec0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e   and [sqlite3_in
1ed0: 74 36 34 5d 20 74 79 70 65 20 73 68 61 6c 6c 20  t64] type shall 
1ee0: 73 70 65 63 69 66 79 0a 2a 2a 20 20 20 20 20 20  specify.**      
1ef0: 20 20 20 20 61 20 36 34 2d 62 69 74 20 73 69 67      a 64-bit sig
1f00: 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1f10: 2a 2a 20 7b 48 31 30 32 30 32 7d 20 54 68 65 20  ** {H10202} The 
1f20: 5b 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20  [sqlite_uint64] 
1f30: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e  and [sqlite3_uin
1f40: 74 36 34 5d 20 74 79 70 65 20 73 68 61 6c 6c 20  t64] type shall 
1f50: 73 70 65 63 69 66 79 0a 2a 2a 20 20 20 20 20 20  specify.**      
1f60: 20 20 20 20 61 20 36 34 2d 62 69 74 20 75 6e 73      a 64-bit uns
1f70: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a  igned integer..*
1f80: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
1f90: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
1fa0: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
1fb0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
1fc0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
1fd0: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
1fe0: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
1ff0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
2000: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2010: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2020: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2030: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2040: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2050: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2060: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2070: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2080: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2090: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
20a0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
20b0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
20c0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
20d0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
20e0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
20f0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2100: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2110: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2120: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2130: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2140: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2150: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2160: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2170: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2180: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2190: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
21a0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
21b0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
21c0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
21d0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
21e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
21f0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2200: 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 30  Connection {H120
2210: 31 30 7d 20 3c 53 33 30 31 30 30 3e 3c 53 34 30  10} <S30100><S40
2220: 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  200>.**.** This 
2230: 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64  routine is the d
2240: 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
2250: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2260: 63 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ct..**.** Applic
2270: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73  ations should [s
2280: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2290: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20  | finalize] all 
22a0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22b0: 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  ents].** and [sq
22c0: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
22d0: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
22e0: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73  LOB handles] ass
22f0: 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
2300: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2310: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
2320: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
2330: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a  e the object..**
2340: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65   The [sqlite3_ne
2350: 78 74 5f 73 74 6d 74 28 29 5d 20 69 6e 74 65 72  xt_stmt()] inter
2360: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
2370: 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a   to locate all.*
2380: 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2390: 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69 61 74  ements] associat
23a0: 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ed with a [datab
23b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
23c0: 69 66 20 64 65 73 69 72 65 64 2e 0a 2a 2a 20 54  if desired..** T
23d0: 79 70 69 63 61 6c 20 63 6f 64 65 20 6d 69 67 68  ypical code migh
23e0: 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73  t look like this
23f0: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2400: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c  ote><pre>.** sql
2410: 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2420: 3b 0a 2a 2a 20 77 68 69 6c 65 28 20 28 70 53 74  ;.** while( (pSt
2430: 6d 74 20 3d 20 73 71 6c 69 74 65 33 5f 6e 65 78  mt = sqlite3_nex
2440: 74 5f 73 74 6d 74 28 64 62 2c 20 30 29 29 21 3d  t_stmt(db, 0))!=
2450: 30 20 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  0 ){.** &nbsp;  
2460: 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2470: 65 28 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a  e(pStmt);.** }.*
2480: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
2490: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b  uote>.**.** If [
24a0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
24b0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c   is invoked whil
24c0: 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  e a transaction 
24d0: 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20  is open,.** the 
24e0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61  transaction is a
24f0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
2500: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
2510: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2520: 2a 20 7b 48 31 32 30 31 31 7d 20 41 20 73 75 63  * {H12011} A suc
2530: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2540: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2550: 29 5d 20 73 68 61 6c 6c 20 64 65 73 74 72 6f 79  )] shall destroy
2560: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2570: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2580: 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 20 43 2e  ction] object C.
2590: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 32 7d 20  .**.** {H12012} 
25a0: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
25b0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  l to [sqlite3_cl
25c0: 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c 20 72 65  ose(C)] shall re
25d0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  turn SQLITE_OK..
25e0: 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 33 7d 20 41  **.** {H12013} A
25f0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
2600: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
2610: 73 65 28 43 29 5d 20 73 68 61 6c 6c 20 72 65 6c  se(C)] shall rel
2620: 65 61 73 65 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  ease all.**     
2630: 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20       memory and 
2640: 73 79 73 74 65 6d 20 72 65 73 6f 75 72 63 65 73  system resources
2650: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2660: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2670: 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20  ction].**       
2680: 20 20 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32     C..**.** {H12
2690: 30 31 34 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b  014} A call to [
26a0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
26b0: 5d 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65  ] on a [database
26c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 20 74   connection] C t
26d0: 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
26e0: 68 61 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  has one or more 
26f0: 6f 70 65 6e 20 5b 70 72 65 70 61 72 65 64 20 73  open [prepared s
2700: 74 61 74 65 6d 65 6e 74 73 5d 20 73 68 61 6c 6c  tatements] shall
2710: 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20   fail with.**   
2720: 20 20 20 20 20 20 20 61 6e 20 5b 53 51 4c 49 54         an [SQLIT
2730: 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 63 6f  E_BUSY] error co
2740: 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31  de..**.** {H1201
2750: 35 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71  5} A call to [sq
2760: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
2770: 77 68 65 72 65 20 43 20 69 73 20 61 20 4e 55 4c  where C is a NUL
2780: 4c 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 0a  L pointer shall.
2790: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
27a0: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a  rn SQLITE_OK..**
27b0: 0a 2a 2a 20 7b 48 31 32 30 31 39 7d 20 57 68 65  .** {H12019} Whe
27c0: 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  n [sqlite3_close
27d0: 28 43 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20  (C)] is invoked 
27e0: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
27f0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 0a 2a 2a 20  onnection] C.** 
2800: 20 20 20 20 20 20 20 20 20 74 68 61 74 20 68 61           that ha
2810: 73 20 61 20 70 65 6e 64 69 6e 67 20 74 72 61 6e  s a pending tran
2820: 73 61 63 74 69 6f 6e 2c 20 74 68 65 20 74 72 61  saction, the tra
2830: 6e 73 61 63 74 69 6f 6e 20 73 68 61 6c 6c 20 62  nsaction shall b
2840: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f  e.**          ro
2850: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
2860: 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
2870: 0a 2a 2a 20 7b 41 31 32 30 31 36 7d 20 54 68 65  .** {A12016} The
2880: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
2890: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
28a0: 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  )] must be eithe
28b0: 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20  r a NULL.**     
28c0: 20 20 20 20 20 70 6f 69 6e 74 65 72 20 6f 72 20       pointer or 
28d0: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
28e0: 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61  ect pointer obta
28f0: 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ined.**         
2900: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f   from [sqlite3_o
2910: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
2920: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  _open16()], or.*
2930: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2940: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2950: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2960: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e  ly closed..*/.in
2970: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  t sqlite3_close(
2980: 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a  sqlite3 *);../*.
2990: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
29a0: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
29b0: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
29c0: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
29d0: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
29e0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
29f0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
2a00: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
2a10: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
2a20: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
2a30: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
2a40: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
2a50: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
2a60: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
2a70: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
2a80: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20  ution Interface 
2a90: 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30 30 30  {H12100} <S10000
2aa0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
2ab0: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2ac0: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2ad0: 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e 6e  ient way of runn
2ae0: 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  ing one or more.
2af0: 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
2b00: 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67  s without having
2b10: 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f 74 20   to write a lot 
2b20: 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65 20  of C code.  The 
2b30: 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a 2a  UTF-8 encoded.**
2b40: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
2b50: 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61 73  are passed in as
2b60: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
2b70: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2b80: 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65 20  _exec()..** The 
2b90: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
2ba0: 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79 20  valuated one by 
2bb0: 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 65 72  one until either
2bc0: 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a 20   an error or.** 
2bd0: 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73 20  an interrupt is 
2be0: 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72 20  encountered, or 
2bf0: 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20 61  until they are a
2c00: 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33 72  ll done.  The 3r
2c10: 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  d parameter.** i
2c20: 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63 61  s an optional ca
2c30: 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20 69  llback that is i
2c40: 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
2c50: 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79 20  each row of any 
2c60: 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74 73  query.** results
2c70: 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68 65   produced by the
2c80: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
2c90: 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65    The 5th parame
2ca0: 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65 0a  ter tells where.
2cb0: 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79 20  ** to write any 
2cc0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e 0a  error messages..
2cd0: 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72 20  **.** The error 
2ce0: 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 20 62  message passed b
2cf0: 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20  ack through the 
2d00: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  5th parameter is
2d10: 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f   held.** in memo
2d20: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
2d30: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2d40: 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20 61  ()].  To avoid a
2d50: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a   memory leak,.**
2d60: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 70 70   the calling app
2d70: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
2d80: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
2d90: 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72 72  ee()] on any err
2da0: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72 65  or.** message re
2db0: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
2dc0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2dd0: 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
2de0: 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74  ished using.** t
2df0: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
2e00: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
2e10: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
2e20: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2e30: 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  r is NULL or an 
2e40: 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a 20  empty string.** 
2e50: 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74  or a string cont
2e60: 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69 74  aining only whit
2e70: 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d 65  espace and comme
2e80: 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c  nts, then no SQL
2e90: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 61  .** statements a
2ea0: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
2eb0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
2ec0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a   not changed..**
2ed0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2ee0: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
2ef0: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
2f00: 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b  in terms of.** [
2f10: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2f20: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
2f30: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
2f40: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2f50: 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  ]..** The sqlite
2f60: 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e 65  3_exec() routine
2f70: 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f   does nothing to
2f80: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68   the database th
2f90: 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e  at cannot be don
2fa0: 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  e.** by [sqlite3
2fb0: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2fc0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2fd0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fe0: 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a  inalize()]..**.*
2ff0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
3000: 0a 2a 2a 20 7b 48 31 32 31 30 31 7d 20 41 20 73  .** {H12101} A s
3010: 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
3020: 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
3030: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3040: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ].**          sh
3050: 61 6c 6c 20 73 65 71 75 65 6e 74 69 61 6c 6c 79  all sequentially
3060: 20 65 76 61 6c 75 61 74 65 20 61 6c 6c 20 6f 66   evaluate all of
3070: 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
3080: 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed,.**          
3090: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
30a0: 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
30b0: 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
30c0: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20  erminated.**    
30d0: 20 20 20 20 20 20 73 74 72 69 6e 67 20 53 20 77        string S w
30e0: 69 74 68 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ithin the contex
30f0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
3100: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
3110: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 32 7d  ..**.** {H12102}
3120: 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d 65   If the S parame
3130: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3140: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d  exec(D,S,C,A,E)]
3150: 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a   is NULL then.**
3160: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 63            the ac
3170: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 69 6e 74  tions of the int
3180: 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62 65 20  erface shall be 
3190: 74 68 65 20 73 61 6d 65 20 61 73 20 69 66 20 74  the same as if t
31a0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  he.**          S
31b0: 20 70 61 72 61 6d 65 74 65 72 20 77 65 72 65 20   parameter were 
31c0: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
31d0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 34 7d 20  .**.** {H12104} 
31e0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
31f0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   of [sqlite3_exe
3200: 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 5b 53  c()] shall be [S
3210: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6c 6c  QLITE_OK] if all
3220: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
3230: 20 73 74 61 74 65 6d 65 6e 74 73 20 72 75 6e 20   statements run 
3240: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 6e 64  successfully and
3250: 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
3260: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 35 7d 20 54  **.** {H12105} T
3270: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
3280: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  of [sqlite3_exec
3290: 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 61 6e 20  ()] shall be an 
32a0: 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 20  appropriate.**  
32b0: 20 20 20 20 20 20 20 20 6e 6f 6e 2d 7a 65 72 6f          non-zero
32c0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
32d0: 20 61 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   any SQL stateme
32e0: 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  nt fails..**.** 
32f0: 7b 48 31 32 31 30 37 7d 20 49 66 20 6f 6e 65 20  {H12107} If one 
3300: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 53  or more of the S
3310: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 68 61  QL statements ha
3320: 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  nded to [sqlite3
3330: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20  _exec()].**     
3340: 20 20 20 20 20 72 65 74 75 72 6e 20 72 65 73 75       return resu
3350: 6c 74 73 20 61 6e 64 20 74 68 65 20 33 72 64 20  lts and the 3rd 
3360: 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 74  parameter is not
3370: 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a 2a 20 20   NULL, then.**  
3380: 20 20 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c          the call
3390: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 70  back function sp
33a0: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 33  ecified by the 3
33b0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 68 61  rd parameter sha
33c0: 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20  ll be.**        
33d0: 20 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66    invoked once f
33e0: 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 72  or each row of r
33f0: 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  esult..**.** {H1
3400: 32 31 31 30 7d 20 49 66 20 74 68 65 20 63 61 6c  2110} If the cal
3410: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20  lback returns a 
3420: 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 20 74  non-zero value t
3430: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  hen [sqlite3_exe
3440: 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  c()].**         
3450: 20 73 68 61 6c 6c 20 61 62 6f 72 74 20 74 68 65   shall abort the
3460: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
3470: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 65  t is currently e
3480: 76 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20 20 20  valuating,.**   
3490: 20 20 20 20 20 20 20 73 6b 69 70 20 61 6c 6c 20         skip all 
34a0: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
34b0: 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 72  tatements, and r
34c0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 41 42  eturn [SQLITE_AB
34d0: 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ORT]..**.** {H12
34e0: 31 31 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  113} The [sqlite
34f0: 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e  3_exec()] routin
3500: 65 20 73 68 61 6c 6c 20 70 61 73 73 20 69 74 73  e shall pass its
3510: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
3520: 68 72 6f 75 67 68 0a 2a 2a 20 20 20 20 20 20 20  hrough.**       
3530: 20 20 20 61 73 20 74 68 65 20 31 73 74 20 70 61     as the 1st pa
3540: 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 63  rameter of the c
3550: 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b  allback..**.** {
3560: 48 31 32 31 31 36 7d 20 54 68 65 20 5b 73 71 6c  H12116} The [sql
3570: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75  ite3_exec()] rou
3580: 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74  tine shall set t
3590: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
35a0: 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20   of its.**      
35b0: 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20      callback to 
35c0: 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
35d0: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
35e0: 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a 2a  current row of.*
35f0: 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
3600: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 39  t..**.** {H12119
3610: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
3620: 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73  xec()] routine s
3630: 68 61 6c 6c 20 73 65 74 20 74 68 65 20 33 72 64  hall set the 3rd
3640: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74   parameter of it
3650: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  s.**          ca
3660: 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20  llback to be an 
3670: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
3680: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c  s to strings hol
3690: 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ding the.**     
36a0: 20 20 20 20 20 76 61 6c 75 65 73 20 66 6f 72 20       values for 
36b0: 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74  each column in t
36c0: 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c  he current resul
36d0: 74 20 73 65 74 20 72 6f 77 20 61 73 0a 2a 2a 20  t set row as.** 
36e0: 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65           obtaine
36f0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
3700: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
3710: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 32 7d 20 54  **.** {H12122} T
3720: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
3730: 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c  ()] routine shal
3740: 6c 20 73 65 74 20 74 68 65 20 34 74 68 20 70 61  l set the 4th pa
3750: 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a  rameter of its.*
3760: 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
3770: 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72  ack to be an arr
3780: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3790: 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e  o strings holdin
37a0: 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  g the.**        
37b0: 20 20 6e 61 6d 65 73 20 6f 66 20 72 65 73 75 6c    names of resul
37c0: 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20 6f 62 74  t columns as obt
37d0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
37e0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
37f0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32  )]..**.** {H1212
3800: 35 7d 20 49 66 20 74 68 65 20 33 72 64 20 70 61  5} If the 3rd pa
3810: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
3820: 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 4e  te3_exec()] is N
3830: 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  ULL then.**     
3840: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78       [sqlite3_ex
3850: 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 69 6c 65  ec()] shall sile
3860: 6e 74 6c 79 20 64 69 73 63 61 72 64 20 71 75 65  ntly discard que
3870: 72 79 20 72 65 73 75 6c 74 73 2e 0a 2a 2a 0a 2a  ry results..**.*
3880: 2a 20 7b 48 31 32 31 33 31 7d 20 49 66 20 61 6e  * {H12131} If an
3890: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
38a0: 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72 20 65  ile parsing or e
38b0: 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20 6f 66  valuating any of
38c0: 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20 20   the SQL.**     
38d0: 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20       statements 
38e0: 69 6e 20 74 68 65 20 53 20 70 61 72 61 6d 65 74  in the S paramet
38f0: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  er of [sqlite3_e
3900: 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20  xec(D,S,C,A,E)] 
3910: 61 6e 64 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  and if.**       
3920: 20 20 20 74 68 65 20 45 20 70 61 72 61 6d 65 74     the E paramet
3930: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
3940: 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78  then [sqlite3_ex
3950: 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 74 6f 72  ec()] shall stor
3960: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
3970: 20 2a 45 20 61 6e 20 61 70 70 72 6f 70 72 69 61   *E an appropria
3980: 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
3990: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
39a0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  mory obtained.**
39b0: 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b            from [
39c0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
39d0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 34  ]..**.** {H12134
39e0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
39f0: 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20  xec(D,S,C,A,E)] 
3a00: 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65  routine shall se
3a10: 74 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  t the value of.*
3a20: 2a 20 20 20 20 20 20 20 20 20 20 2a 45 20 74 6f  *          *E to
3a30: 20 4e 55 4c 4c 20 69 66 20 45 20 69 73 20 6e 6f   NULL if E is no
3a40: 74 20 4e 55 4c 4c 20 61 6e 64 20 74 68 65 72 65  t NULL and there
3a50: 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a   are no errors..
3a60: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 37 7d 20 54  **.** {H12137} T
3a70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
3a80: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 66 75 6e  (D,S,C,A,E)] fun
3a90: 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20  ction shall set 
3aa0: 74 68 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  the [error code]
3ab0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
3ac0: 20 6d 65 73 73 61 67 65 20 61 63 63 65 73 73 69   message accessi
3ad0: 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ble via [sqlite3
3ae0: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
3af0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3b00: 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64  3_errmsg()], and
3b10: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3b20: 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  16()]..**.** {H1
3b30: 32 31 33 38 7d 20 49 66 20 74 68 65 20 53 20 70  2138} If the S p
3b40: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
3b50: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c  ite3_exec(D,S,C,
3b60: 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72  A,E)] is NULL or
3b70: 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
3b80: 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
3b90: 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67  contains nothing
3ba0: 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74   other than whit
3bb0: 65 73 70 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73  espace, comments
3bc0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  ,.**          an
3bd0: 64 2f 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c  d/or semicolons,
3be0: 20 74 68 65 6e 20 72 65 73 75 6c 74 73 20 6f 66   then results of
3bf0: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
3c00: 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  e()],.**        
3c10: 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73    [sqlite3_errms
3c20: 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  g()], and [sqlit
3c30: 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a  e3_errmsg16()].*
3c40: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
3c50: 20 72 65 73 65 74 20 74 6f 20 69 6e 64 69 63 61   reset to indica
3c60: 74 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a  te no errors..**
3c70: 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
3c80: 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 31 7d 20  .**.** {A12141} 
3c90: 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
3ca0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3cb0: 65 78 65 63 28 29 5d 20 6d 75 73 74 20 62 65 20  exec()] must be 
3cc0: 61 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65  an valid and ope
3cd0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  n.**          [d
3ce0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3cf0: 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31  on]..**.** {A121
3d00: 34 32 7d 20 54 68 65 20 64 61 74 61 62 61 73 65  42} The database
3d10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
3d20: 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20 77   not be closed w
3d30: 68 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  hile.**         
3d40: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3d50: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ] is running..**
3d60: 0a 2a 2a 20 7b 41 31 32 31 34 33 7d 20 54 68 65  .** {A12143} The
3d70: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
3d80: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71  n should use [sq
3d90: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f  lite3_free()] to
3da0: 20 66 72 65 65 0a 2a 2a 20 20 20 20 20 20 20 20   free.**        
3db0: 20 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61    the memory tha
3dc0: 74 20 2a 65 72 72 6d 73 67 20 69 73 20 6c 65 66  t *errmsg is lef
3dd0: 74 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 6f 6e  t pointing at on
3de0: 63 65 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ce the error.** 
3df0: 20 20 20 20 20 20 20 20 20 6d 65 73 73 61 67 65           message
3e00: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
3e10: 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  eded..**.** {A12
3e20: 31 34 35 7d 20 54 68 65 20 53 51 4c 20 73 74 61  145} The SQL sta
3e30: 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 20 74  tement text in t
3e40: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
3e50: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
3e60: 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  c()].**         
3e70: 20 6d 75 73 74 20 72 65 6d 61 69 6e 20 75 6e 63   must remain unc
3e80: 68 61 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 71  hanged while [sq
3e90: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
3ea0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
3eb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
3ec0: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
3ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ee0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
3ef0: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
3f00: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
3f10: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
3f20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3f30: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
3f40: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
3f50: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
3f60: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
3f70: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
3f80: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
3f90: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
3fa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fb0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
3fc0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
3fd0: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
3fe0: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
3ff0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4000: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
4010: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
4020: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
4030: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
4040: 43 6f 64 65 73 20 7b 48 31 30 32 31 30 7d 20 3c  Codes {H10210} <
4050: 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10700>.** KEYWO
4060: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
4070: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
4080: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4090: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
40a0: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
40b0: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
40c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
40d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
40e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
40f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4100: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4110: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73  r to indicates s
4120: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
4130: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
4140: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
4150: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
4160: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
4170: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
4180: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  so: [SQLITE_IOER
4190: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
41a0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a  d result codes].
41b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
41c0: 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30  E_OK           0
41d0: 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c     /* Successful
41e0: 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65   result */./* be
41f0: 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72  ginning-of-error
4200: 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e  -codes */.#defin
4210: 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20  e SQLITE_ERROR  
4220: 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c        1   /* SQL
4230: 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e   error or missin
4240: 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  g database */.#d
4250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4260: 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a  ERNAL     2   /*
4270: 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20   Internal logic 
4280: 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20  error in SQLite 
4290: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42a0: 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33  E_PERM         3
42b0: 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72     /* Access per
42c0: 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a  mission denied *
42d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
42e0: 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20  _ABORT        4 
42f0: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f    /* Callback ro
4300: 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20  utine requested 
4310: 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66  an abort */.#def
4320: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  ine SQLITE_BUSY 
4330: 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54          5   /* T
4340: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
4350: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
4360: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4370: 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a  KED       6   /*
4380: 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20   A table in the 
4390: 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b  database is lock
43a0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
43b0: 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20  LITE_NOMEM      
43c0: 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f    7   /* A mallo
43d0: 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64  c() failed */.#d
43e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
43f0: 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a  DONLY     8   /*
4400: 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74   Attempt to writ
4410: 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74  e a readonly dat
4420: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
4430: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50   SQLITE_INTERRUP
4440: 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72  T    9   /* Oper
4450: 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64  ation terminated
4460: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   by sqlite3_inte
4470: 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e  rrupt()*/.#defin
4480: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20  e SQLITE_IOERR  
4490: 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d       10   /* Som
44a0: 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49  e kind of disk I
44b0: 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65  /O error occurre
44c0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
44d0: 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20  ITE_CORRUPT     
44e0: 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  11   /* The data
44f0: 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20  base disk image 
4500: 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a  is malformed */.
4510: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4520: 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20  OTFOUND    12   
4530: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62  /* NOT USED. Tab
4540: 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74  le or record not
4550: 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e   found */.#defin
4560: 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20  e SQLITE_FULL   
4570: 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73       13   /* Ins
4580: 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65  ertion failed be
4590: 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69  cause database i
45a0: 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e  s full */.#defin
45b0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
45c0: 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61  N    14   /* Una
45d0: 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ble to open the 
45e0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
45f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4600: 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20  PROTOCOL    15  
4610: 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61   /* NOT USED. Da
4620: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4630: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4640: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4650: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4660: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4670: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
4680: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
4690: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
46a0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
46b0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
46c0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
46d0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
46e0: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
46f0: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4700: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4710: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4720: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4730: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4740: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4750: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4760: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4770: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
4780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4790: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
47a0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
47b0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
47c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
47d0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
47e0: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
47f0: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4800: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4820: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4830: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4840: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4850: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4860: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4870: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
4880: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
4890: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
48a0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
48b0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
48c0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
48d0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
48f0: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4900: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4910: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4920: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20  fine SQLITE_ROW 
4940: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
4950: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4960: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
4970: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
4980: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
4990: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
49a0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
49b0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
49c0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
49d0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
49e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
49f0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
4a00: 64 65 73 20 7b 48 31 30 32 32 30 7d 20 3c 53 31  des {H10220} <S1
4a10: 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0700>.** KEYWORD
4a20: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72  S: {extended err
4a30: 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64  or code} {extend
4a40: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a  ed error codes}.
4a50: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78  ** KEYWORDS: {ex
4a60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4a70: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65  de} {extended re
4a80: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
4a90: 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74  * In its default
4aa0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
4ab0: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69  SQLite API routi
4ac0: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  nes return one o
4ad0: 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20  f 26 integer.** 
4ae0: 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73  [SQLITE_OK | res
4af0: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
4b00: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
4b10: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20   has shown that 
4b20: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65  many of.** these
4b30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4b40: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61  e too coarse-gra
4b50: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
4b60: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
4b70: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
4b80: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
4b90: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
4ba0: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
4bb0: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
4bc0: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
4bd0: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
4be0: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
4bf0: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29  3.3.8 and later)
4c00: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70   include.** supp
4c10: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ort for addition
4c20: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  al result codes 
4c30: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72  that provide mor
4c40: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
4c50: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
4c60: 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65  errors. The exte
4c70: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4c80: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72  s are enabled or
4c90: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20   disabled.** on 
4ca0: 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63  a per database c
4cb0: 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20  onnection basis 
4cc0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
4cd0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
4ce0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41  esult_codes()] A
4cf0: 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f  PI..**.** Some o
4d00: 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  f the available 
4d10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4d20: 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64  codes are listed
4d30: 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61   here..** One ma
4d40: 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d  y expect the num
4d50: 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20  ber of extended 
4d60: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c  result codes wil
4d70: 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f  l be expand.** o
4d80: 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77  ver time.  Softw
4d90: 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78  are that uses ex
4da0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4db0: 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63  des should expec
4dc0: 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20  t.** to see new 
4dd0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20  result codes in 
4de0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
4df0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
4e00: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72   The SQLITE_OK r
4e10: 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20  esult code will 
4e20: 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65  never be extende
4e30: 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61  d.  It will alwa
4e40: 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79  ys.** be exactly
4e50: 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   zero..**.** INV
4e60: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
4e70: 48 31 30 32 32 33 7d 20 54 68 65 20 73 79 6d 62  H10223} The symb
4e80: 6f 6c 69 63 20 6e 61 6d 65 20 66 6f 72 20 61 6e  olic name for an
4e90: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4ea0: 20 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74   code shall cont
4eb0: 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ains.**         
4ec0: 20 61 20 72 65 6c 61 74 65 64 20 70 72 69 6d 61   a related prima
4ed0: 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61  ry result code a
4ee0: 73 20 61 20 70 72 65 66 69 78 2e 0a 2a 2a 0a 2a  s a prefix..**.*
4ef0: 2a 20 7b 48 31 30 32 32 34 7d 20 50 72 69 6d 61  * {H10224} Prima
4f00: 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e  ry result code n
4f10: 61 6d 65 73 20 73 68 61 6c 6c 20 63 6f 6e 74 61  ames shall conta
4f20: 69 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f 22 20  in a single "_" 
4f30: 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a  character..**.**
4f40: 20 7b 48 31 30 32 32 35 7d 20 45 78 74 65 6e 64   {H10225} Extend
4f50: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e  ed result code n
4f60: 61 6d 65 73 20 73 68 61 6c 6c 20 63 6f 6e 74 61  ames shall conta
4f70: 69 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22  in two or more "
4f80: 5f 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  _" characters..*
4f90: 2a 0a 2a 2a 20 7b 48 31 30 32 32 36 7d 20 54 68  *.** {H10226} Th
4fa0: 65 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  e numeric value 
4fb0: 6f 66 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72  of an extended r
4fc0: 65 73 75 6c 74 20 63 6f 64 65 20 73 68 61 6c 6c  esult code shall
4fd0: 20 63 6f 6e 74 61 69 6e 20 74 68 65 0a 2a 2a 20   contain the.** 
4fe0: 20 20 20 20 20 20 20 20 20 6e 75 6d 65 72 69 63           numeric
4ff0: 20 76 61 6c 75 65 20 6f 66 20 69 74 73 20 63 6f   value of its co
5000: 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 69 6d  rresponding prim
5010: 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ary result code 
5020: 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  in.**          i
5030: 74 73 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ts least signifi
5040: 63 61 6e 74 20 38 20 62 69 74 73 2e 0a 2a 2f 0a  cant 8 bits..*/.
5050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5060: 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20  OERR_READ       
5070: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5080: 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23  OERR | (1<<8)).#
5090: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50a0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20  ERR_SHORT_READ  
50b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50c0: 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ERR | (2<<8)).#d
50d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50e0: 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20  RR_WRITE        
50f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5100: 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  RR | (3<<8)).#de
5110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5120: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
5130: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5140: 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  R | (4<<8)).#def
5150: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5160: 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20  _DIR_FSYNC      
5170: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5180: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
5190: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
51a0: 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20  TRUNCATE        
51b0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51c0: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (6<<8)).#defin
51d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
51e0: 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20  STAT            
51f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5200: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
5210: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e   SQLITE_IOERR_UN
5220: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5230: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5240: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
5250: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c  SQLITE_IOERR_RDL
5260: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
5270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5280: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
5290: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
52a0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53  TE            (S
52b0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
52c0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
52d0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
52e0: 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53  KED           (S
52f0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5300: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5310: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45  QLITE_IOERR_NOME
5320: 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  M             (S
5330: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5340: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5350: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45  QLITE_IOERR_ACCE
5360: 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53  SS            (S
5370: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5380: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5390: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43  QLITE_IOERR_CHEC
53a0: 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53  KRESERVEDLOCK (S
53b0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
53c0: 34 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  4<<8))../*.** CA
53d0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
53e0: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
53f0: 61 74 69 6f 6e 73 20 7b 48 31 30 32 33 30 7d 20  ations {H10230} 
5400: 3c 48 31 31 31 32 30 3e 20 3c 48 31 32 37 30 30  <H11120> <H12700
5410: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  >.**.** These bi
5420: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5430: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5440: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5450: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5460: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5470: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5480: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5490: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78 4f  ameter to the xO
54a0: 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  pen method of th
54b0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
54c0: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
54d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
54e0: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20  N_READONLY      
54f0: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
5500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5510: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20  N_READWRITE     
5520: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5540: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20  N_CREATE        
5550: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
5560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5570: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20  N_DELETEONCLOSE 
5580: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
5590: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
55a0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  N_EXCLUSIVE     
55b0: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
55c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
55d0: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20  N_MAIN_DB       
55e0: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
55f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5600: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20  N_TEMP_DB       
5610: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
5620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5630: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20  N_TRANSIENT_DB  
5640: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64     0x00000400.#d
5650: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5660: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20  N_MAIN_JOURNAL  
5670: 20 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64     0x00000800.#d
5680: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5690: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20  N_TEMP_JOURNAL  
56a0: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
56b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
56c0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20  N_SUBJOURNAL    
56d0: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 64     0x00002000.#d
56e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
56f0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
5700: 20 20 20 30 78 30 30 30 30 34 30 30 30 0a 23 64     0x00004000.#d
5710: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5720: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20  N_NOMUTEX       
5730: 20 20 20 30 78 30 30 30 30 38 30 30 30 0a 0a 2f     0x00008000../
5740: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
5750: 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69  evice Characteri
5760: 73 74 69 63 73 20 7b 48 31 30 32 34 30 7d 20 3c  stics {H10240} <
5770: 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H11120>.**.** Th
5780: 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69 6c  e xDeviceCapabil
5790: 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20  ities method of 
57a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
57b0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
57c0: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
57d0: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
57e0: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74   vector of the t
57f0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
5800: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
5810: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
5820: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
5830: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
5840: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
5850: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
5860: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5870: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
5880: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
5890: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
58a0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
58b0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
58c0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
58d0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
58e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
58f0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
5900: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
5910: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
5920: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
5930: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
5940: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
5950: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
5960: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
5970: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
5980: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
5990: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
59a0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
59b0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
59c0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
59d0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
59e0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
59f0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
5a00: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
5a10: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
5a20: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
5a30: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
5a40: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5a50: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
5a60: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
5a70: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
5a80: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
5a90: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
5aa0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
5ab0: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
5ac0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5ad0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
5ae0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
5af0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5b00: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20  OCAP_ATOMIC512  
5b10: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
5b20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5b30: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
5b40: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
5b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5b60: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
5b70: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
5b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5b90: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
5ba0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
5bb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5bc0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
5bd0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
5be0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5bf0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
5c00: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
5c10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5c20: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
5c30: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
5c40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5c50: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
5c60: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a       0x00000100.
5c70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5c80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5c90: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
5ca0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5cb0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5cc0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
5cd0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5ce0: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
5cf0: 76 65 6c 73 20 7b 48 31 30 32 35 30 7d 20 3c 48  vels {H10250} <H
5d00: 31 31 31 32 30 3e 20 3c 48 31 31 33 31 30 3e 0a  11120> <H11310>.
5d10: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5d20: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5d30: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5d40: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5d50: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5d60: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5d70: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5d80: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5d90: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5da0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5db0: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5dc0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5dd0: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5de0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5df0: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5e00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5e10: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5e20: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5e30: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5e40: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5e50: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5e60: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5e70: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5e80: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5e90: 65 20 46 6c 61 67 73 20 7b 48 31 30 32 36 30 7d  e Flags {H10260}
5ea0: 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20   <H11120>.**.** 
5eb0: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
5ec0: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
5ed0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
5ee0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5ef0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
5f00: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
5f10: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
5f20: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
5f30: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
5f40: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
5f50: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
5f60: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
5f70: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
5f80: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
5f90: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
5fa0: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
5fb0: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
5fc0: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
5fd0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
5fe0: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
5ff0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
6000: 4e 4f 52 4d 41 4c 20 66 6c 61 67 20 6d 65 61 6e  NORMAL flag mean
6010: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d  s.** to use norm
6020: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
6030: 74 69 63 73 2e 20 54 68 65 20 53 51 4c 49 54 45  tics. The SQLITE
6040: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20  _SYNC_FULL flag 
6050: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
6060: 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66  Mac OS-X style f
6070: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
6080: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23  of fsync()..*/.#
6090: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
60a0: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
60b0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
60c0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
60d0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
60e0: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
60f0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6100: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
6110: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6120: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
6130: 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 31 31  File Handle {H11
6140: 31 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a  110} <S20110>.**
6150: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
6160: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
6170: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
6180: 66 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a  file in the OS.*
6190: 2a 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  * interface laye
61a0: 72 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  r.  Individual O
61b0: 53 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c  S interface impl
61c0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
61d0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
61e0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
61f0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
6200: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
6210: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
6220: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
6230: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
6240: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
6250: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6260: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
6270: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
6280: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
6290: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
62a0: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
62b0: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
62c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
62d0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
62e0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
62f0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
6300: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
6310: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
6320: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
6330: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
6340: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
6350: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
6360: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
6370: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
6380: 20 7b 48 31 31 31 32 30 7d 20 3c 53 32 30 31 31   {H11120} <S2011
6390: 30 3e 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  0>.**.** Every f
63a0: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
63b0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
63c0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70  xOpen method pop
63d0: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
63e0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
63f0: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
6400: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
6410: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
6420: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
6430: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
6440: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
6450: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
6460: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
6470: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
6480: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
6490: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
64a0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
64b0: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
64c0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
64d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
64e0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
64f0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
6500: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6510: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6520: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6530: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6540: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6550: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6560: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6570: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6580: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6590: 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS-X style fulls
65a0: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
65b0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
65c0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
65d0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
65e0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
65f0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
6600: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6610: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6620: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6630: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6640: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6650: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6660: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6670: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6680: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6690: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
66a0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
66b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
66c0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
66d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
66e0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
66f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6700: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6710: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6720: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6730: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6740: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6750: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6760: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6770: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6780: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6790: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
67a0: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
67b0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
67c0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
67d0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
67e0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
67f0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
6800: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6810: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6820: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6830: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6840: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6850: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6860: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6870: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6880: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6890: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
68a0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
68b0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
68c0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
68d0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
68e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
68f0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
6900: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6910: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6920: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6930: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6940: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6950: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6960: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6970: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6980: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6990: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
69a0: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
69b0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
69c0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
69d0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
69e0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
69f0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
6a00: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6a10: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6a20: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6a30: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6a40: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6a50: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6a60: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6a70: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6a80: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6a90: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6aa0: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
6ab0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
6ac0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
6ad0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
6ae0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
6af0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
6b00: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6b10: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6b20: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6b30: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6b40: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6b50: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6b60: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6b70: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6b80: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6b90: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6ba0: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6bb0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6bc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6bd0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6be0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6bf0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6c00: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6c10: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6c20: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6c30: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6c40: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6c50: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6c60: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6c70: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6c80: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6c90: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6ca0: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6cb0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6cc0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6cd0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6ce0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6cf0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6d00: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6d10: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6d20: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6d30: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6d40: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6d50: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6d60: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6d70: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6d80: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6d90: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6da0: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6db0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6dc0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6dd0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6de0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6df0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6e00: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6e10: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6e20: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6e30: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6e40: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6e50: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6e60: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6e70: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6e80: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6e90: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6ea0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6eb0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6ec0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6ed0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6ee0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6ef0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6f00: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6f10: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6f20: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6f30: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6f40: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6f50: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6f60: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6f70: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6f80: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6f90: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6fa0: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
6fb0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
6fc0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
6fd0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
6fe0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
6ff0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
7000: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
7010: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
7020: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
7030: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
7040: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
7050: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
7060: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
7070: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
7080: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
7090: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
70a0: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
70b0: 72 69 74 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  rite()..*/.typed
70c0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
70d0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
70e0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
70f0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
7100: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
7110: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
7120: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
7130: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7140: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
7150: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
7160: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
7170: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
7180: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
7190: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
71a0: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
71b0: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
71c0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
71d0: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
71e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
71f0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
7200: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
7210: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
7220: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
7230: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
7240: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7250: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
7260: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
7270: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
7280: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
7290: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
72a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
72b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
72c0: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
72d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
72e0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
72f0: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
7300: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7310: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
7320: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
7330: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
7340: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7350: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
7360: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
7370: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
7380: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
7390: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
73a0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
73b0: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
73c0: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
73d0: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
73e0: 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d  Opcodes {H11310}
73f0: 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30800>.**.** 
7400: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
7410: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
7420: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
7430: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
7440: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
7450: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7460: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
7470: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
7480: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
7490: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
74a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
74b0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
74c0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
74d0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
74e0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
74f0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
7500: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
7510: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
7520: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
7530: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
7540: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
7550: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7560: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
7570: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
7580: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7590: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
75a0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
75b0: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
75c0: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
75d0: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
75e0: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
75f0: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
7600: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
7610: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
7620: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
7630: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
7640: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
7650: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
7660: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
7670: 54 45 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a  TE        1../*.
7680: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
7690: 65 78 20 48 61 6e 64 6c 65 20 7b 48 31 37 31 31  ex Handle {H1711
76a0: 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a  0} <S20130>.**.*
76b0: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
76c0: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
76d0: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
76e0: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
76f0: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
7700: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
7710: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
7720: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
7730: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
7740: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
7750: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
7760: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
7770: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
7780: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
7790: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
77a0: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
77b0: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
77c0: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
77d0: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
77e0: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
77f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
7800: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
7810: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
7820: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7830: 65 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 34 30  e Object {H11140
7840: 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20100>.**.**
7850: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
7860: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
7870: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
7880: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
7890: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
78a0: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
78b0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
78c0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
78d0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
78e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
78f0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
7900: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
7910: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  stem"..**.** The
7920: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
7930: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
7940: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
7950: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
7960: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
7970: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
7980: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
7990: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
79a0: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
79b0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
79c0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
79d0: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
79e0: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
79f0: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
7a00: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
7a10: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
7a20: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
7a30: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
7a40: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
7a50: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
7a60: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
7a70: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
7a80: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
7a90: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
7aa0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
7ab0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
7ac0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
7ad0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
7ae0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
7af0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
7b00: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
7b10: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
7b20: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
7b30: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
7b40: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
7b50: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
7b60: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
7b70: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
7b80: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
7b90: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
7ba0: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
7bb0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
7bc0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
7bd0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
7be0: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
7bf0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
7c00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
7c10: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
7c20: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
7c30: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
7c40: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
7c50: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
7c60: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
7c70: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
7c80: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
7c90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
7ca0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
7cb0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
7cc0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
7cd0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
7ce0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
7cf0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
7d00: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
7d10: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
7d20: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
7d30: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
7d40: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
7d50: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
7d60: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
7d70: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
7d80: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
7d90: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
7da0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
7db0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
7dc0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
7dd0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
7de0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
7df0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
7e00: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
7e10: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
7e20: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
7e30: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34  es..**.** {H1114
7e40: 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  1} SQLite will g
7e50: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
7e60: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
7e70: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
7e80: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
7e90: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
7ea0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
7eb0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
7ec0: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
7ed0: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
7ee0: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
7ef0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
7f00: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
7f10: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
7f20: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 7b 45  is.** called. {E
7f30: 4e 44 7d 20 20 42 65 63 61 75 73 65 20 6f 66 20  ND}  Because of 
7f40: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
7f50: 74 65 6e 73 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tense,.** the [s
7f60: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
7f70: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
7f80: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
7f90: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
7fa0: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
7fb0: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
7fc0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
7fd0: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
7fe0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
7ff0: 73 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  s xOpen is a NUL
8000: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
8010: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
8020: 69 74 65 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ite its own temp
8030: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
8040: 68 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76  he file.  Whenev
8050: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
8060: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
8070: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
8080: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
8090: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
80a0: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
80b0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
80c0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
80d0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  OSE]..**.** {H11
80e0: 31 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61  142} The flags a
80f0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8100: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
8110: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** 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 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
8140: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8150: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8160: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
8170: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
8180: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
8190: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
81a0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
81b0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
81c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
81d0: 45 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20  E]. {END}.** If 
81e0: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
81f0: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
8200: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
8210: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
8220: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
8230: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
8240: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
8250: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
8260: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 33  t..**.** {H11143
8270: 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  } SQLite will al
8280: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
8290: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
82a0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
82b0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
82c0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
82d0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
82e0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
82f0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8300: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
8310: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8320: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
8330: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
8340: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
8350: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8360: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
8370: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8380: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
8390: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
83a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
83b0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
83c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
83d0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
83e0: 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  </ul> {END}.**.*
83f0: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
8400: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
8410: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
8420: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
8430: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
8440: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
8450: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
8460: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
8470: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
8480: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
8490: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
84a0: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
84b0: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
84c0: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
84d0: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
84e0: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
84f0: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
8500: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
8510: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
8520: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
8530: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
8540: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
8550: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
8560: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
8570: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
8580: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
8590: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
85a0: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
85b0: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
85c0: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
85d0: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
85e0: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
85f0: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
8600: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
8610: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
8620: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
8630: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
8640: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
8650: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
8660: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8670: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
8680: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
8690: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
86a0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34  ul>.**.** {H1114
86b0: 35 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  5} The [SQLITE_O
86c0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
86d0: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
86e0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
86f0: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
8700: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
8710: 7b 48 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51  {H11146} The [SQ
8720: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
8730: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
8740: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
8750: 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75    databases, jou
8760: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75  rnals and for su
8770: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
8780: 20 7b 48 31 31 31 34 37 7d 20 54 68 65 20 5b 53   {H11147} The [S
8790: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
87a0: 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  SIVE] flag means
87b0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
87c0: 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f   be opened.** fo
87d0: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
87e0: 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69  ss.  This flag i
87f0: 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69  s set for all fi
8800: 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f  les except.** fo
8810: 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  r the main datab
8820: 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  ase file..**.** 
8830: 7b 48 31 31 31 34 38 7d 20 41 74 20 6c 65 61 73  {H11148} At leas
8840: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
8850: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
8860: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
8870: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
8880: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
8890: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
88a0: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
88b0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
88c0: 4f 70 65 6e 2e 20 7b 45 4e 44 7d 20 20 54 68 65  Open. {END}  The
88d0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
88e0: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
88f0: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
8900: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
8910: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
8920: 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31   in..**.** {H111
8930: 34 39 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72  49} The flags ar
8940: 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73  gument to xAcces
8950: 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49  s() may be [SQLI
8960: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
8970: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72  ].** to test for
8980: 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f   the existence o
8990: 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51  f a file, or [SQ
89a0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
89b0: 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73  WRITE] to.** tes
89c0: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
89d0: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
89e0: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
89f0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
8a00: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68  D].** to test wh
8a10: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
8a20: 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c  at least readabl
8a30: 65 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 66 69  e. {END}  The fi
8a40: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
8a50: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
8a60: 7b 48 31 31 31 35 30 7d 20 53 51 4c 69 74 65 20  {H11150} SQLite 
8a70: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
8a80: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
8a90: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
8aa0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
8ab0: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
8ac0: 61 74 68 6e 61 6d 65 2e 20 7b 48 31 31 31 35 31  athname. {H11151
8ad0: 7d 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65  } The exact size
8ae0: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
8af0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
8b00: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
8b10: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
8b20: 6d 65 74 68 6f 64 73 2e 20 7b 45 4e 44 7d 20 20  methods. {END}  
8b30: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
8b40: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
8b50: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
8b60: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
8b70: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
8b80: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
8b90: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
8ba0: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
8bb0: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
8bc0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
8bd0: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
8be0: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
8bf0: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
8c00: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
8c10: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
8c20: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
8c30: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
8c40: 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72  eep(), and xCurr
8c50: 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66  entTime() interf
8c60: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
8c70: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
8c80: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
8c90: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
8ca0: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
8cb0: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
8cc0: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
8cd0: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
8ce0: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
8cf0: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
8d00: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
8d10: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
8d20: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
8d30: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
8d40: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
8d50: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
8d60: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
8d70: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
8d80: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
8d90: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
8da0: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
8db0: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
8dc0: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
8dd0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
8de0: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
8df0: 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69    The xCurrentTi
8e00: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
8e10: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
8e20: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
8e30: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
8e40: 61 6e 64 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70  and time..*/.typ
8e50: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
8e60: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
8e70: 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  vfs;.struct sqli
8e80: 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20  te3_vfs {.  int 
8e90: 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20  iVersion;       
8ea0: 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72       /* Structur
8eb0: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
8ec0: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
8ed0: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
8ee0: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
8ef0: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
8f00: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
8f10: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
8f20: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
8f30: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
8f40: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
8f50: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
8f60: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
8f70: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
8f80: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
8f90: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
8fa0: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
8fb0: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
8fc0: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
8fd0: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
8fe0: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
8ff0: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
9000: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
9010: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
9020: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
9030: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
9040: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
9050: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
9060: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
9070: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
9080: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
9090: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
90a0: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
90b0: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
90c0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
90d0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
90e0: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
90f0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
9100: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
9110: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
9120: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
9130: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
9140: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
9150: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
9160: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9170: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
9180: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
9190: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
91a0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
91b0: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
91c0: 20 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69   *(*xDlSym)(sqli
91d0: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
91e0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
91f0: 62 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  bol);.  void (*x
9200: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
9210: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
9220: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
9230: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
9240: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
9250: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
9260: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
9270: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
9280: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
9290: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
92a0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
92b0: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
92c0: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
92d0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
92e0: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
92f0: 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20   New fields may 
9300: 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66  be appended in f
9310: 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20  igure versions. 
9320: 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20   The iVersion.  
9330: 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e  ** value will in
9340: 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72  crement whenever
9350: 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a   this happens. *
9360: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
9370: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
9380: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
9390: 6d 65 74 68 6f 64 20 7b 48 31 31 31 39 30 7d 20  method {H11190} 
93a0: 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 7b  <H11140>.**.** {
93b0: 48 31 31 31 39 31 7d 20 54 68 65 73 65 20 69 6e  H11191} These in
93c0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
93d0: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
93e0: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
93f0: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
9400: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
9410: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
9420: 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54  object. {END}  T
9430: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
9440: 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65   what kind of pe
9450: 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41  rmissions the xA
9460: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20  ccess method is 
9470: 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20  looking for..** 
9480: 7b 48 31 31 31 39 32 7d 20 57 69 74 68 20 53 51  {H11192} With SQ
9490: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
94a0: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
94b0: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
94c0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
94d0: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
94e0: 0a 2a 2a 20 7b 48 31 31 31 39 33 7d 20 57 69 74  .** {H11193} Wit
94f0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
9500: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
9510: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
9520: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
9530: 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68  the file is both
9540: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
9550: 69 74 61 62 6c 65 2e 0a 2a 2a 20 7b 48 31 31 31  itable..** {H111
9560: 39 34 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f  94} With SQLITE_
9570: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
9580: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
9590: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
95a0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
95b0: 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69  adable..*/.#defi
95c0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
95d0: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
95e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
95f0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23  SS_READWRITE 1.#
9600: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
9610: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
9620: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9630: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
9640: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20   SQLite Library 
9650: 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30  {H10130} <S20000
9660: 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S30100>.**.** 
9670: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9680: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9690: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
96a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
96b0: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
96c0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
96d0: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
96e0: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
96f0: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
9700: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
9710: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
9720: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
9730: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9740: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
9750: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
9760: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
9770: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
9780: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
9790: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
97a0: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
97b0: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
97c0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
97d0: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
97e0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
97f0: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
9800: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
9810: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9820: 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63  .  Only an effec
9830: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
9840: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9850: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
9860: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
9870: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
9880: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
9890: 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  o-ops..**.** Amo
98a0: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
98b0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
98c0: 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f  ize() shall invo
98d0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
98e0: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
98f0: 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75  rly, sqlite3_shu
9900: 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c  tdown().** shall
9910: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
9920: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
9930: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9940: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9950: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
9960: 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  OK on success..*
9970: 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65  * If for some re
9980: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
9990: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
99a0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
99b0: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
99c0: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
99d0: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
99e0: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
99f0: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
9a00: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
9a10: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
9a20: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
9a30: 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a  SQLITE_OK..**.**
9a40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
9a50: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
9a60: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
9a70: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
9a80: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
9a90: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
9aa0: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
9ab0: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
9ac0: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
9ad0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
9ae0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
9af0: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
9b00: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
9b10: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
9b20: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9b30: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
9b40: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
9b50: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
9b60: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
9b70: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
9b80: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
9b90: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
9ba0: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
9bb0: 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66  dy.  However, if
9bc0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
9bd0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
9be0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
9bf0: 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  T.** compile-tim
9c00: 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
9c10: 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
9c20: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
9c30: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
9c40: 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
9c50: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
9c60: 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
9c70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
9c80: 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
9c90: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
9ca0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
9cb0: 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
9cc0: 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
9cd0: 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
9ce0: 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
9cf0: 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
9d00: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
9d10: 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
9d20: 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
9d30: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
9d40: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
9d50: 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
9d60: 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
9d70: 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
9d80: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
9d90: 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
9da0: 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
9db0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
9dc0: 64 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4f 4d  d with SQLITE_OM
9dd0: 49 54 5f 41 55 54 4f 49 4e 49 54 20 6d 69 67 68  IT_AUTOINIT migh
9de0: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
9df0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
9e00: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
9e10: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
9e20: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
9e30: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
9e40: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
9e50: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
9e60: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
9e70: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
9e80: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
9e90: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
9ea0: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
9eb0: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
9ec0: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
9ed0: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
9ee0: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
9ef0: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
9f00: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
9f10: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
9f20: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
9f30: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
9f40: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
9f50: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
9f60: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
9f70: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
9f80: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
9f90: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
9fa0: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
9fb0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
9fc0: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
9fd0: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
9fe0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
9ff0: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
a000: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
a010: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
a020: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
a030: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
a040: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
a050: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
a060: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a070: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
a080: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
a090: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
a0a0: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
a0b0: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
a0c0: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
a0d0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a0e0: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
a0f0: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
a100: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
a110: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
a120: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
a130: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
a140: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a150: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
a160: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
a170: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
a180: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
a190: 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e  ed for unix, win
a1a0: 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a  dows, or os/2..*
a1b0: 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f 72  * When built for
a1c0: 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
a1d0: 20 28 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49   (using the SQLI
a1e0: 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 20 63 6f  TE_OS_OTHER=1 co
a1f0: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
a200: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
a210: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
a220: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
a230: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
a240: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
a250: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
a260: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
a270: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
a280: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
a290: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
a2a0: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
a2b0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
a2c0: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53 51  * must return SQ
a2d0: 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65  LITE_OK on succe
a2e0: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
a2f0: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
a300: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
a310: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
a320: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
a330: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
a340: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
a350: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
a360: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
a370: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
a380: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
a390: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
a3a0: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
a3b0: 79 20 7b 48 31 30 31 34 35 7d 20 3c 53 32 30 30  y {H10145} <S200
a3c0: 30 30 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a 0a 2a  00><S30200>.**.*
a3d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
a3e0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
a3f0: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
a400: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
a410: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
a420: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
a430: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
a440: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
a450: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
a460: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
a470: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
a480: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
a490: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
a4a0: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
a4b0: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
a4c0: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
a4d0: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
a4e0: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
a4f0: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
a500: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
a510: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
a520: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
a530: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
a540: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
a550: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
a560: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
a570: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
a580: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
a590: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
a5a0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
a5b0: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
a5c0: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
a5d0: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
a5e0: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
a5f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
a600: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
a610: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
a620: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
a630: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
a640: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
a650: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
a660: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
a670: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
a680: 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
a690: 72 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  r, that sqlite3_
a6a0: 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
a6b0: 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
a6c0: 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
a6d0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
a6e0: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
a6f0: 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
a700: 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
a710: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
a720: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
a730: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
a740: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r.** [SQLITE_CON
a750: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
a760: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
a770: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
a780: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
a790: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
a7a0: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
a7b0: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
a7c0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
a7d0: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
a7e0: 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   on the [SQLITE_
a7f0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
a800: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  EAD | configurat
a810: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
a820: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
a830: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
a840: 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
a850: 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
a860: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a870: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
a880: 4f 4b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  OK..** If the op
a890: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
a8a0: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
a8b0: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
a8c0: 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
a8d0: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
a8e0: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
a8f0: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
a900: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
a910: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
a920: 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
a930: 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 20 74  xperimental in t
a940: 68 61 74 0a 2a 2a 20 6e 65 77 20 63 6f 6e 66 69  hat.** new confi
a950: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
a960: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
a970: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
a980: 20 61 6e 64 20 65 78 69 73 74 69 6e 67 0a 2a 2a   and existing.**
a990: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
a9a0: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 64 69  ptions may be di
a9b0: 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 6d 6f  scontinued or mo
a9c0: 64 69 66 69 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  dified..*/.int s
a9d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
a9e0: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
a9f0: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
aa00: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
aa10: 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 3c 53  ines {H10155} <S
aa20: 32 30 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20  20120>.**.** An 
aa30: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
aa40: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
aa50: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
aa60: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
aa70: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
aa80: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
aa90: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
aaa0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
aab0: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
aac0: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
aad0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
aae0: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
aaf0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
ab00: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
ab10: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
ab20: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ab30: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
ab40: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ab50: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
ab60: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
ab70: 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
ab80: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
ab90: 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
aba0: 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
abb0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 64  ite3_config()] d
abc0: 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  uring configurat
abd0: 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c 69  ion, an.** appli
abe0: 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
abf0: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
ac00: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
ac10: 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a  ion subsystem.**
ac20: 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
ac30: 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
ac40: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
ac50: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   needs..**.** No
ac60: 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  te that SQLite c
ac70: 6f 6d 65 73 20 77 69 74 68 20 61 20 62 75 69 6c  omes with a buil
ac80: 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
ac90: 63 61 74 6f 72 20 74 68 61 74 20 69 73 0a 2a 2a  cator that is.**
aca0: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
acb0: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
acc0: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
acd0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
ace0: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
acf0: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
ad00: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
ad10: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
ad20: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
ad30: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
ad40: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ad50: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
ad60: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
ad70: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
ad80: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
ad90: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
ada0: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
adb0: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
adc0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
add0: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
ade0: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
adf0: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
ae00: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
ae10: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
ae20: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
ae30: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
ae40: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
ae50: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 46   The xMalloc, xF
ae60: 72 65 65 2c 20 61 6e 64 20 78 52 65 61 6c 6c 6f  ree, and xReallo
ae70: 63 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  c methods must w
ae80: 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
ae90: 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65 65 28 29  malloc(), free()
aea0: 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63 28 29 20  , and realloc() 
aeb0: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
aec0: 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72  he standard libr
aed0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  ary..**.** xSize
aee0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
aef0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
af00: 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
af10: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
af20: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
af30: 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
af40: 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
af50: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
af60: 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
af70: 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
af80: 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
af90: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
afa0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
afb0: 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
afc0: 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
afd0: 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
afe0: 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
aff0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b000: 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
b010: 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
b020: 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
b030: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
b040: 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
b050: 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
b060: 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
b070: 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
b080: 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
b090: 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
b0a0: 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
b0b0: 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
b0c0: 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  f 2..**.** The x
b0d0: 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
b0e0: 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
b0f0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28  ry allocator.  (
b100: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
b110: 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
b120: 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
b130: 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
b140: 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
b150: 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
b160: 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
b170: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
b180: 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
b190: 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
b1a0: 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
b1b0: 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
b1c0: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
b1d0: 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
b1e0: 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
b1f0: 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
b200: 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
b210: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
b220: 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
b230: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
b240: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
b250: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
b260: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
b270: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
b280: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
b290: 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
b2a0: 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
b2b0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b2c0: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
b2d0: 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
b2e0: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
b2f0: 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
b300: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
b310: 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
b320: 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
b330: 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
b340: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
b350: 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
b360: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
b370: 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
b380: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
b390: 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
b3a0: 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
b3b0: 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
b3c0: 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
b3d0: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
b3e0: 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
b3f0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
b400: 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
b410: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
b420: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
b430: 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
b440: 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
b450: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
b460: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
b470: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
b480: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
b490: 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
b4a0: 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
b4b0: 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
b4c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
b4d0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
b4e0: 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d 20 3c 53  ions {H10160} <S
b4f0: 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20000>.**.** The
b500: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
b510: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
b520: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
b530: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
b540: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
b550: 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
b560: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
b570: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
b580: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
b590: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
b5a0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
b5b0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
b5c0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
b5d0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
b5e0: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
b5f0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
b600: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
b610: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
b620: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
b630: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
b640: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
b650: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
b660: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
b670: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
b680: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
b690: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
b6a0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
b6b0: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
b6c0: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
b6d0: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
b6e0: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
b6f0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
b700: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
b710: 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
b720: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
b730: 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
b740: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
b750: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
b760: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
b770: 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65  s option disable
b780: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
b790: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
b7a0: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
b7b0: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
b7c0: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
b7d0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f  single thread.</
b7e0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
b7f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
b800: 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
b810: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
b820: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
b830: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73  is option.  This
b840: 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73   option disables
b850: 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
b860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
b870: 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
b880: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
b890: 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
b8a0: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
b8b0: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
b8c0: 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
b8d0: 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
b8e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
b8f0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
b900: 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
b910: 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
b920: 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
b930: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
b940: 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
b950: 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
b960: 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
b970: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
b980: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
b990: 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
b9a0: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
b9b0: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
b9c0: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68  this option.  Th
b9d0: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
b9e0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
b9f0: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
ba00: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
ba10: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
ba20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
ba30: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
ba40: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
ba50: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
ba60: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
ba70: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
ba80: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
ba90: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
baa0: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
bab0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
bac0: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
bad0: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
bae0: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
baf0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
bb00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
bb10: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
bb20: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
bb30: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
bb40: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
bb50: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
bb60: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
bb70: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
bb80: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
bb90: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
bba0: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 70 3e   time..**.** <p>
bbb0: 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
bbc0: 6f 6e 20 6f 70 74 69 6f 6e 20 6d 65 72 65 6c 79  on option merely
bbd0: 20 73 65 74 73 20 74 68 65 20 64 65 66 61 75 6c   sets the defaul
bbe0: 74 20 6d 75 74 65 78 20 0a 2a 2a 20 62 65 68 61  t mutex .** beha
bbf0: 76 69 6f 72 20 74 6f 20 73 65 72 69 61 6c 69 7a  vior to serializ
bc00: 65 20 61 63 63 65 73 73 20 74 6f 20 5b 64 61 74  e access to [dat
bc10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bc20: 73 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 0a  s].  Individual.
bc30: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
bc40: 6e 65 63 74 69 6f 6e 73 5d 20 63 61 6e 20 6f 76  nections] can ov
bc50: 65 72 72 69 64 65 20 74 68 69 73 20 73 65 74 74  erride this sett
bc60: 69 6e 67 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  ing.** using the
bc70: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
bc80: 4d 55 54 45 58 5d 20 66 6c 61 67 20 74 6f 20 5b  MUTEX] flag to [
bc90: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
bca0: 29 5d 2e 3c 2f 70 3e 3c 2f 64 64 3e 0a 2a 2a 0a  )].</p></dd>.**.
bcb0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
bcc0: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
bcd0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
bce0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
bcf0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
bd00: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
bd10: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
bd20: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
bd30: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
bd40: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
bd50: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
bd60: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
bd70: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
bd80: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
bd90: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
bda0: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
bdb0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
bdc0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
bdd0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
bde0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bdf0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
be00: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
be10: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
be20: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
be30: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
be40: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
be50: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
be60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
be70: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
be80: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
be90: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
bea0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
beb0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
bec0: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
bed0: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
bee0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
bef0: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
bf00: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
bf10: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
bf20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
bf30: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
bf40: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
bf50: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
bf60: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
bf70: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
bf80: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
bf90: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
bfa0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bfb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
bfc0: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
bfd0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
bfe0: 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 62 6f 6f  takes single boo
bff0: 6c 65 61 6e 20 61 72 67 75 6d 65 6e 74 20 77 68  lean argument wh
c000: 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
c010: 69 73 61 62 6c 65 73 0a 2a 2a 20 74 68 65 20 63  isables.** the c
c020: 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
c030: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
c040: 74 61 74 69 73 74 69 63 73 2e 20 20 57 68 65 6e  tatistics.  When
c050: 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 0a 2a   disabled, the.*
c060: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  * following SQLi
c070: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
c080: 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
c090: 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
c0a0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
c0b0: 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
c0c0: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
c0d0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
c0e0: 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
c0f0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
c100: 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a  _heap_limit()].*
c110: 2a 20 20 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33  *   <li> sqlite3
c120: 5f 6d 65 6d 6f 72 79 5f 73 74 61 74 75 73 28 29  _memory_status()
c130: 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c  .**   </ul>.** <
c140: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
c150: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
c160: 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
c170: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  >This option spe
c180: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
c190: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
c1a0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
c1b0: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
c1c0: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
c1d0: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
c1e0: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
c1f0: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74  to the memory, t
c200: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
c210: 63 68 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ch scratch buffe
c220: 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
c230: 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72  number of buffer
c240: 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
c250: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
c260: 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
c270: 20 31 36 2e 20 54 68 65 20 66 69 72 73 74 0a 2a   16. The first.*
c280: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
c290: 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
c2a0: 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
c2b0: 65 61 73 74 20 28 73 7a 2b 34 29 2a 4e 20 62 79  east (sz+4)*N by
c2c0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
c2d0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  * SQLite will us
c2e0: 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e no more than o
c2f0: 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ne scratch buffe
c300: 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68  r at once per th
c310: 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68  read, so.** N sh
c320: 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
c330: 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
c340: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
c350: 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a  reads.  The sz.*
c360: 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  * parameter shou
c370: 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 74 68  ld be 6 times th
c380: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
c390: 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
c3a0: 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72  age size..** Scr
c3b0: 61 74 63 68 20 62 75 66 66 65 72 73 20 61 72 65  atch buffers are
c3c0: 20 75 73 65 64 20 61 73 20 70 61 72 74 20 6f 66   used as part of
c3d0: 20 74 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e   the btree balan
c3e0: 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49  ce operation.  I
c3f0: 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62  f.** The btree b
c400: 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64  alancer needs ad
c410: 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20  ditional memory 
c420: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
c430: 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63  rovided by.** sc
c440: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 6f 72  ratch buffers or
c450: 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62   if no scratch b
c460: 75 66 66 65 72 20 73 70 61 63 65 20 69 73 20 73  uffer space is s
c470: 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53  pecified, then S
c480: 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f  QLite.** goes to
c490: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
c4a0: 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  ()] to obtain th
c4b0: 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64  e memory it need
c4c0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
c4d0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c4e0: 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
c4f0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
c500: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
c510: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
c520: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
c530: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
c540: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
c550: 63 61 63 68 65 2e 20 20 54 68 65 72 65 20 61 72  cache.  There ar
c560: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
c570: 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: A pointer to 
c580: 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  the.** memory, t
c590: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
c5a0: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
c5b0: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
c5c0: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
c5d0: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
c5e0: 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 77 65  t must be a powe
c5f0: 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
c600: 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 2e 20   512 and 32768. 
c610: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
c620: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
c630: 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
c640: 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
c650: 20 28 73 7a 2b 34 29 2a 4e 20 62 79 74 65 73 20   (sz+4)*N bytes 
c660: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51  of memory..** SQ
c670: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
c680: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
c690: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
c6a0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
c6b0: 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
c6c0: 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
c6d0: 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
c6e0: 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
c6f0: 68 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e  he.  If addition
c700: 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
c710: 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
c720: 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
c730: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
c740: 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
c750: 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
c760: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
c770: 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
c780: 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
c790: 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  pace.</dd>.**.**
c7a0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
c7b0: 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
c7c0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
c7d0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
c7e0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
c7f0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
c800: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
c810: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
c820: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c830: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
c840: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
c850: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
c860: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
c870: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
c880: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
c890: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
c8a0: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70  e arguments: A p
c8b0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
c8c0: 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72  mory, the number
c8d0: 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
c8e0: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
c8f0: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
c900: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
c910: 7a 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 66  ze.  If.** the f
c920: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
c930: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
c940: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
c950: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
c960: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
c970: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
c980: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
c990: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
c9a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
c9b0: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
c9c0: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
c9d0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
c9e0: 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65  MALLOC].  If the
c9f0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
ca00: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  er is not NULL a
ca10: 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  nd either [SQLIT
ca20: 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
ca30: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
ca40: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
ca50: 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65  are defined, the
ca60: 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
ca70: 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
ca80: 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
ca90: 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
caa0: 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
cab0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
cac0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
cad0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
cae0: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
caf0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
cb00: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
cb10: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
cb20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
cb30: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
cb40: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
cb50: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
cb60: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
cb70: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
cb80: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
cb90: 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
cba0: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
cbb0: 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20  in place.** the 
cbc0: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
cbd0: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
cbe0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
cbf0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
cc00: 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
cc10: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
cc20: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
cc30: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
cc40: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
cc50: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
cc60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
cc70: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
cc80: 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
cc90: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
cca0: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
ccb0: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
ccc0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
ccd0: 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
cce0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73  outines..** This
ccf0: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
cd00: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
cd10: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
cd20: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
cd30: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
cd40: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
cd50: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
cd60: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
cd70: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
cd80: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
cd90: 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2f 0a  xample.</dd>.*/.
cda0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
cdb0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
cdc0: 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
cdd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cde0: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
cdf0: 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
ce00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ce10: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
ce20: 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
ce30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ce40: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
ce50: 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
ce60: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
ce70: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
ce80: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
ce90: 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
cea0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
ceb0: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
cec0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
ced0: 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
cee0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
cef0: 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
cf00: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
cf10: 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
cf20: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
cf30: 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
cf40: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
cf50: 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
cf60: 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
cf70: 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
cf80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
cf90: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
cfa0: 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
cfb0: 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
cfc0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
cfd0: 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
cfe0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
cff0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
d000: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
d010: 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
d020: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
d030: 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a  ex_methods* */..
d040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
d050: 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
d060: 20 20 20 31 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f     12  /* nil */
d070: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
d080: 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
d090: 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
d0a0: 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32 32  sult Codes {H122
d0b0: 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  00} <S10700>.**.
d0c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
d0d0: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
d0e0: 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
d0f0: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
d100: 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
d110: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
d120: 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
d130: 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ite. The extende
d140: 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
d150: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
d160: 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
d170: 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
d180: 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72 61  bility considera
d190: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  tions..**.** INV
d1a0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
d1b0: 48 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65 77  H12201} Each new
d1c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
d1d0: 63 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61 76  ction] shall hav
d1e0: 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  e the.**        
d1f0: 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75    [extended resu
d200: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
d210: 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
d220: 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fault..**.** {H1
d230: 32 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  2202} The [sqlit
d240: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
d250: 6c 74 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20 69  lt_codes(D,F)] i
d260: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 65  nterface shall e
d270: 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20  nable.**        
d280: 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75    [extended resu
d290: 6c 74 20 63 6f 64 65 73 5d 20 66 6f 72 20 74 68  lt codes] for th
d2a0: 65 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  e  [database con
d2b0: 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20  nection] D.**   
d2c0: 20 20 20 20 20 20 20 69 66 20 74 68 65 20 46 20         if the F 
d2d0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 72 75  parameter is tru
d2e0: 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  e, or disable th
d2f0: 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73 65  em if F is false
d300: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
d310: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
d320: 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
d330: 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
d340: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
d350: 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20  st Insert Rowid 
d360: 7b 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30  {H12220} <S10700
d370: 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74  >.**.** Each ent
d380: 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
d390: 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
d3a0: 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
d3b0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
d3c0: 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69  called the "rowi
d3d0: 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73  d". The rowid is
d3e0: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
d3f0: 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
d400: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
d410: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
d420: 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
d430: 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
d440: 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
d450: 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
d460: 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
d470: 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20  umns. If.** the 
d480: 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
d490: 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45 47  mn of type INTEG
d4a0: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74  ER PRIMARY KEY t
d4b0: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
d4c0: 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
d4d0: 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
d4e0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  d..**.** This ro
d4f0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
d500: 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d  e rowid of the m
d510: 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75  ost recent.** su
d520: 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20  ccessful INSERT 
d530: 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
d540: 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61  e from the [data
d550: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
d560: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
d570: 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e   argument.  If n
d580: 6f 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53  o successful INS
d590: 45 52 54 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  ERTs.** have eve
d5a0: 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
d5b0: 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  at database conn
d5c0: 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
d5d0: 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
d5e0: 49 66 20 61 6e 20 49 4e 53 45 52 54 20 6f 63 63  If an INSERT occ
d5f0: 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
d600: 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  gger, then the r
d610: 6f 77 69 64 20 6f 66 20 74 68 65 20 69 6e 73 65  owid of the inse
d620: 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72  rted.** row is r
d630: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
d640: 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20  routine as long 
d650: 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69  as the trigger i
d660: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
d670: 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
d680: 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74  er terminates, t
d690: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
d6a0: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
d6b0: 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20  e.** reverts to 
d6c0: 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69  the last value i
d6d0: 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74  nserted before t
d6e0: 68 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64  he trigger fired
d6f0: 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45 52  ..**.** An INSER
d700: 54 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  T that fails due
d710: 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
d720: 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
d730: 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
d740: 6c 20 49 4e 53 45 52 54 20 61 6e 64 20 64 6f 65  l INSERT and doe
d750: 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
d760: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
d770: 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
d780: 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54  ne.  Thus INSERT
d790: 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
d7a0: 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
d7b0: 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
d7c0: 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
d7d0: 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
d7e0: 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
d7f0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
d800: 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
d810: 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
d820: 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20  on fails.  When 
d830: 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
d840: 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
d850: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
d860: 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
d870: 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
d880: 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
d890: 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
d8a0: 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
d8b0: 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
d8c0: 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
d8d0: 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
d8e0: 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
d8f0: 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
d900: 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
d910: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
d920: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
d930: 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
d940: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
d950: 2c 20 61 6e 20 49 4e 53 45 52 54 20 69 73 20 63  , an INSERT is c
d960: 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
d970: 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
d980: 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
d990: 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
d9a0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  back..**.** INVA
d9b0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
d9c0: 31 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  12221} The [sqli
d9d0: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
d9e0: 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f  rowid()] functio
d9f0: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f  n returns the ro
da00: 77 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  wid.**          
da10: 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  of the most rece
da20: 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e  nt successful IN
da30: 53 45 52 54 20 70 65 72 66 6f 72 6d 65 64 20 6f  SERT performed o
da40: 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  n the same.**   
da50: 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
da60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
da70: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
da80: 20 6f 72 20 68 69 67 68 65 72 20 6c 65 76 65 6c   or higher level
da90: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72 69  .**          tri
daa0: 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72  gger context, or
dab0: 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68   zero if there h
dac0: 61 76 65 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c  ave been no qual
dad0: 69 66 79 69 6e 67 20 69 6e 73 65 72 74 73 2e 0a  ifying inserts..
dae0: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 33 7d 20 54  **.** {H12223} T
daf0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
db00: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
db10: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
db20: 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
db30: 20 20 73 61 6d 65 20 76 61 6c 75 65 20 77 68 65    same value whe
db40: 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
db50: 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 20 63  e same trigger c
db60: 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20  ontext.**       
db70: 20 20 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62     immediately b
db80: 65 66 6f 72 65 20 61 6e 64 20 61 66 74 65 72 20  efore and after 
db90: 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a  a ROLLBACK..**.*
dba0: 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
dbb0: 2a 0a 2a 2a 20 7b 41 31 32 32 33 32 7d 20 49 66  *.** {A12232} If
dbc0: 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
dbd0: 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
dbe0: 77 20 49 4e 53 45 52 54 20 6f 6e 20 74 68 65 20  w INSERT on the 
dbf0: 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
dc00: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
dc10: 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
dc20: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
dc30: 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
dc40: 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
dc50: 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
dc60: 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
dc70: 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f  e last insert ro
dc80: 77 69 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  wid,.**         
dc90: 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
dca0: 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
dcb0: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
dcc0: 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
dcd0: 20 20 20 20 20 20 20 20 20 75 6e 70 72 65 64 69           unpredi
dce0: 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
dcf0: 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
dd00: 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
dd10: 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20   new.**         
dd20: 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77   last insert row
dd30: 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  id..*/.sqlite3_i
dd40: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
dd50: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
dd60: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
dd70: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
dd80: 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
dd90: 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31  ows Modified {H1
dda0: 32 32 34 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a  2240} <S10600>.*
ddb0: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
ddc0: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
ddd0: 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
dde0: 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
ddf0: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
de00: 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
de10: 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
de20: 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
de30: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
de40: 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ** on the [datab
de50: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
de60: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
de70: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
de80: 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65  ..** Only change
de90: 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
dea0: 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
deb0: 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44   the INSERT, UPD
dec0: 41 54 45 2c 0a 2a 2a 20 6f 72 20 44 45 4c 45 54  ATE,.** or DELET
ded0: 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20  E statement are 
dee0: 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69  counted.  Auxili
def0: 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
df00: 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72  ed by.** trigger
df10: 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  s are not counte
df20: 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69  d. Use the [sqli
df30: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
df40: 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  s()] function.**
df50: 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74   to find the tot
df60: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  al number of cha
df70: 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63  nges including c
df80: 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
df90: 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a   triggers..**.**
dfa0: 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20   A "row change" 
dfb0: 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
dfc0: 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
dfd0: 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
dfe0: 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
dff0: 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
e000: 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
e010: 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
e020: 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
e030: 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
e040: 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
e050: 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a  nt resolution,.*
e060: 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52  * rollback, ABOR
e070: 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52  T processing, DR
e080: 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20  OP TABLE, or by 
e090: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63  any other.** mec
e0a0: 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63  hanisms do not c
e0b0: 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72  ount as direct r
e0c0: 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a  ow changes..**.*
e0d0: 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
e0e0: 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
e0f0: 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
e100: 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
e110: 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
e120: 63 72 69 70 74 20 6f 66 20 61 20 74 72 69 67 67  cript of a trigg
e130: 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74  er.  Most SQL st
e140: 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
e150: 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64  evaluated outsid
e160: 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72  e of any trigger
e170: 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22  .  This is the "
e180: 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72  top level".** tr
e190: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20  igger context.  
e1a0: 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72  If a trigger fir
e1b0: 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  es from the top 
e1c0: 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20  level, a.** new 
e1d0: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20  trigger context 
e1e0: 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74  is entered for t
e1f0: 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74  he duration of t
e200: 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67  hat one.** trigg
e210: 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73  er.  Subtriggers
e220: 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65   create subconte
e230: 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75  xts for their du
e240: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61  ration..**.** Ca
e250: 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
e260: 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
e270: 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
e280: 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e  sively does.** n
e290: 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  ot create a new 
e2a0: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
e2b0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
e2c0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
e2d0: 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
e2e0: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
e2f0: 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
e300: 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
e310: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
e320: 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
e330: 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
e340: 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
e350: 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c  * Thus, when cal
e360: 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  led from the top
e370: 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e   level, this fun
e380: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
e390: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
e3a0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
e3b0: 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
e3c0: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
e3d0: 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f  ETE.** that also
e3e0: 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65   occurred at the
e3f0: 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 74   top level.  Wit
e400: 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
e410: 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68  a trigger,.** th
e420: 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
e430: 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  s() interface ca
e440: 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66  n be called to f
e450: 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
e460: 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  f.** changes in 
e470: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
e480: 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
e490: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
e4a0: 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
e4b0: 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  nt within the bo
e4c0: 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74  dy of the same t
e4d0: 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76  rigger..** Howev
e4e0: 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72  er, the number r
e4f0: 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
e500: 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
e510: 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
e520: 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
e530: 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72  those have their
e540: 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a   own context..**
e550: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
e560: 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e  ments the comman
e570: 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  d "DELETE FROM t
e580: 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20  able" without a 
e590: 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20  WHERE clause.** 
e5a0: 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20  by dropping and 
e5b0: 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74  recreating the t
e5c0: 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20  able.  (This is 
e5d0: 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e  much faster than
e5e0: 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67   going.** throug
e5f0: 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69  h and deleting i
e600: 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e  ndividual elemen
e610: 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c  ts from the tabl
e620: 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 20  e.)  Because of 
e630: 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61  this.** optimiza
e640: 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69  tion, the deleti
e650: 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46  ons in "DELETE F
e660: 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e  ROM table" are n
e670: 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61  ot row changes a
e680: 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62  nd.** will not b
e690: 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65  e counted by the
e6a0: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
e6b0: 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74  () or [sqlite3_t
e6c0: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a  otal_changes()].
e6d0: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65  ** functions, re
e6e0: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
e6f0: 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e  number of elemen
e700: 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69  ts that were ori
e710: 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68  ginally.** in th
e720: 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74  e table.  To get
e730: 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75   an accurate cou
e740: 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
e750: 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64   of rows deleted
e760: 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45  , use.** "DELETE
e770: 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52   FROM table WHER
e780: 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a  E 1" instead..**
e790: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
e7a0: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 31 7d 20 54  **.** {H12241} T
e7b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
e7c0: 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ges()] function 
e7d0: 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65  shall return the
e7e0: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20   number of.**   
e7f0: 20 20 20 20 20 20 20 72 6f 77 20 63 68 61 6e 67         row chang
e800: 65 73 20 63 61 75 73 65 64 20 62 79 20 74 68 65  es caused by the
e810: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
e820: 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20  ERT, UPDATE,.** 
e830: 20 20 20 20 20 20 20 20 20 6f 72 20 44 45 4c 45           or DELE
e840: 54 45 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20  TE statement on 
e850: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
e860: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64  e connection and
e870: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
e880: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20  hin the same or 
e890: 68 69 67 68 65 72 20 74 72 69 67 67 65 72 20 63  higher trigger c
e8a0: 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20  ontext, or zero 
e8b0: 69 66 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a  if there have.**
e8c0: 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65            not be
e8d0: 65 6e 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e  en any qualifyin
e8e0: 67 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a  g row changes..*
e8f0: 2a 0a 2a 2a 20 7b 48 31 32 32 34 33 7d 20 53 74  *.** {H12243} St
e900: 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20  atements of the 
e910: 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f  form "DELETE FRO
e920: 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74  M tablename" wit
e930: 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  h no.**         
e940: 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 73 68   WHERE clause sh
e950: 61 6c 6c 20 63 61 75 73 65 20 73 75 62 73 65 71  all cause subseq
e960: 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
e970: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
e980: 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 74 6f  e3_changes()] to
e990: 20 72 65 74 75 72 6e 20 7a 65 72 6f 2c 20 72 65   return zero, re
e9a0: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 0a  gardless of the.
e9b0: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
e9c0: 65 72 20 6f 66 20 72 6f 77 73 20 6f 72 69 67 69  er of rows origi
e9d0: 6e 61 6c 6c 79 20 69 6e 20 74 68 65 20 74 61 62  nally in the tab
e9e0: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  le..**.** ASSUMP
e9f0: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
ea00: 32 32 35 32 7d 20 49 66 20 61 20 73 65 70 61 72  2252} If a separ
ea10: 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
ea20: 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
ea30: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
ea40: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
ea50: 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69       while [sqli
ea60: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
ea70: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
ea80: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
ea90: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  d.**          is
eaa0: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
eab0: 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
eac0: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
ead0: 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
eae0: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
eaf0: 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
eb00: 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
eb10: 69 65 64 20 7b 48 31 32 32 36 30 7d 20 3c 53 31  ied {H12260} <S1
eb20: 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0600>.**.** This
eb30: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
eb40: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
eb50: 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
eb60: 65 64 20 62 79 20 49 4e 53 45 52 54 2c 0a 2a 2a  ed by INSERT,.**
eb70: 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
eb80: 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  E statements sin
eb90: 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ce the [database
eba0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73   connection] was
ebb0: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20   opened..** The 
ebc0: 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61  count includes a
ebd0: 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20  ll changes from 
ebe0: 61 6c 6c 20 74 72 69 67 67 65 72 20 63 6f 6e 74  all trigger cont
ebf0: 65 78 74 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a  exts.  However,.
ec00: 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65  ** the count doe
ec10: 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
ec20: 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d  anges used to im
ec30: 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43 45 20  plement REPLACE 
ec40: 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20  constraints,.** 
ec50: 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20  do rollbacks or 
ec60: 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
ec70: 2c 20 6f 72 20 44 52 4f 50 20 74 61 62 6c 65 20  , or DROP table 
ec80: 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54  processing..** T
ec90: 68 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  he changes are c
eca0: 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  ounted as soon a
ecb0: 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
ecc0: 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20  that makes them 
ecd0: 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  is.** completed 
ece0: 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
ecf0: 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61  ent handle is pa
ed00: 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
ed10: 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
ed20: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
ed30: 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  e()])..**.** SQL
ed40: 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
ed50: 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45  he command "DELE
ed60: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77  TE FROM table" w
ed70: 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63  ithout a WHERE c
ed80: 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70  lause.** by drop
ed90: 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74  ping and recreat
eda0: 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20  ing the table.  
edb0: 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61  (This is much fa
edc0: 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a  ster than going.
edd0: 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64  ** through and d
ede0: 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75  eleting individu
edf0: 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d  al elements from
ee00: 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65   the table.)  Be
ee10: 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a  cause of this.**
ee20: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74   optimization, t
ee30: 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20  he deletions in 
ee40: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
ee50: 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20  le" are not row 
ee60: 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77  changes and.** w
ee70: 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74  ill not be count
ee80: 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
ee90: 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b  3_changes() or [
eea0: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
eeb0: 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63  anges()].** func
eec0: 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 73  tions, regardles
eed0: 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  s of the number 
eee0: 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74  of elements that
eef0: 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79   were originally
ef00: 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c 65  .** in the table
ef10: 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63  .  To get an acc
ef20: 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74  urate count of t
ef30: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
ef40: 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a  s deleted, use.*
ef50: 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  * "DELETE FROM t
ef60: 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e  able WHERE 1" in
ef70: 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  stead..**.** See
ef80: 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
ef90: 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
efa0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
efb0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
efc0: 20 7b 48 31 32 32 36 31 7d 20 54 68 65 20 5b 73   {H12261} The [s
efd0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
efe0: 6e 67 65 73 28 29 5d 20 72 65 74 75 72 6e 73 20  nges()] returns 
eff0: 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
f000: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
f010: 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
f020: 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50  ed by INSERT, UP
f030: 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45 4c  DATE, and/or DEL
f040: 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ETE.**          
f050: 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74 68  statements on th
f060: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
f070: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69 6e   connection], in
f080: 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 20 20 20   any.**         
f090: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
f0a0: 2c 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  , since the data
f0b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
f0c0: 77 61 73 20 63 72 65 61 74 65 64 2e 0a 2a 2a 0a  was created..**.
f0d0: 2a 2a 20 7b 48 31 32 32 36 33 7d 20 53 74 61 74  ** {H12263} Stat
f0e0: 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f  ements of the fo
f0f0: 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  rm "DELETE FROM 
f100: 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68 20  tablename" with 
f110: 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 57  no.**          W
f120: 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c  HERE clause shal
f130: 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  l not change the
f140: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
f150: 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b  **          by [
f160: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
f170: 61 6e 67 65 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  anges()]..**.** 
f180: 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
f190: 2a 2a 20 7b 41 31 32 32 36 34 7d 20 49 66 20 61  ** {A12264} If a
f1a0: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
f1b0: 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
f1c0: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
f1d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
f1e0: 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65  *          while
f1f0: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
f200: 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
f210: 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
f220: 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
f230: 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
f240: 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
f250: 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
f260: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
f270: 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
f280: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
f290: 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
f2a0: 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
f2b0: 20 51 75 65 72 79 20 7b 48 31 32 32 37 30 7d 20   Query {H12270} 
f2c0: 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30500>.**.** T
f2d0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
f2e0: 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
f2f0: 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
f300: 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
f310: 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
f320: 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
f330: 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
f340: 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
f350: 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
f360: 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
f370: 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
f380: 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
f390: 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
f3a0: 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
f3b0: 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
f3c0: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
f3d0: 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
f3e0: 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73  y..**.** It is s
f3f0: 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
f400: 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
f410: 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
f420: 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
f430: 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
f440: 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
f450: 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
f460: 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
f470: 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
f480: 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
f490: 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
f4a0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
f4b0: 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
f4c0: 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
f4d0: 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
f4e0: 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
f4f0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ns..**.** If an 
f500: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
f510: 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
f520: 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
f530: 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
f540: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
f550: 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
f560: 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
f570: 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
f580: 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
f590: 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
f5a0: 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
f5b0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53  tion..**.** An S
f5c0: 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
f5d0: 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
f5e0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
f5f0: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
f600: 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65 72  .** If the inter
f610: 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
f620: 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
f630: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
f640: 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
f650: 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
f660: 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
f670: 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
f680: 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
f690: 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
f6a0: 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
f6b0: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
f6c0: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
f6d0: 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66 66  upt() has no eff
f6e0: 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
f6f0: 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
f700: 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
f710: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f720: 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
f730: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
f740: 2a 0a 2a 2a 20 7b 48 31 32 32 37 31 7d 20 54 68  *.** {H12271} Th
f750: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
f760: 72 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61 63  rupt()] interfac
f770: 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c 6c  e will force all
f780: 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20   running.**     
f790: 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
f7a0: 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
f7b0: 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 61 74  ith the same dat
f7c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f7d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
f7e0: 68 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63 65  halt after proce
f7f0: 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f 6e  ssing at most on
f800: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f 77  e additional row
f810: 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
f820: 7b 48 31 32 32 37 32 7d 20 41 6e 79 20 53 51 4c  {H12272} Any SQL
f830: 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
f840: 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 62  is interrupted b
f850: 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  y [sqlite3_inter
f860: 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20  rupt()].**      
f870: 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e 20      will return 
f880: 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
f890: 54 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  T]..**.** ASSUMP
f8a0: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
f8b0: 32 32 37 39 7d 20 49 66 20 74 68 65 20 64 61 74  2279} If the dat
f8c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f8d0: 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73   closes while [s
f8e0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
f8f0: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
f900: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
f910: 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
f920: 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
f930: 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
f940: 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
f950: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
f960: 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
f970: 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
f980: 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b  nt Is Complete {
f990: 48 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30 3e  H10510} <S70200>
f9a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
f9b0: 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
f9c0: 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e   for command-lin
f9d0: 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
f9e0: 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
f9f0: 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
fa00: 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
fa10: 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20 53  orm complete a S
fa20: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
fa30: 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
fa40: 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
fa50: 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
fa60: 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
fa70: 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
fa80: 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ing.  These rout
fa90: 69 6e 65 73 20 72 65 74 75 72 6e 20 74 72 75 65  ines return true
faa0: 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
fab0: 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
fac0: 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
fad0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
fae0: 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20   A statement is 
faf0: 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
fb00: 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
fb10: 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
fb20: 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
fb30: 73 20 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e 74  s not a fragment
fb40: 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54 45 20   of a.** CREATE 
fb50: 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
fb60: 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  t.  Semicolons t
fb70: 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
fb80: 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
fb90: 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
fba0: 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
fbb0: 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
fbc0: 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
fbd0: 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
fbe0: 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
fbf0: 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
fc00: 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
fc10: 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
fc20: 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
fc30: 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
fc40: 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
fc50: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
fc60: 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
fc70: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
fc80: 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
fc90: 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
fca0: 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
fcb0: 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   SQL..**.** INVA
fcc0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
fcd0: 31 30 35 31 31 7d 20 41 20 73 75 63 63 65 73 73  10511} A success
fce0: 66 75 6c 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ful evaluation o
fcf0: 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  f [sqlite3_compl
fd00: 65 74 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ete()] or.**    
fd10: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
fd20: 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 66 75 6e  omplete16()] fun
fd30: 63 74 69 6f 6e 73 20 73 68 61 6c 6c 0a 2a 2a 20  ctions shall.** 
fd40: 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
fd50: 61 20 6e 75 6d 65 72 69 63 20 31 20 69 66 20 61  a numeric 1 if a
fd60: 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 6c  nd only if the l
fd70: 61 73 74 20 6e 6f 6e 2d 77 68 69 74 65 73 70 61  ast non-whitespa
fd80: 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ce.**          t
fd90: 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 20 69 6e  oken in their in
fda0: 70 75 74 20 69 73 20 61 20 73 65 6d 69 63 6f 6c  put is a semicol
fdb0: 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 69  on that is not i
fdc0: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 20 20 20  n between.**    
fdd0: 20 20 20 20 20 20 74 68 65 20 42 45 47 49 4e 20        the BEGIN 
fde0: 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 43 52 45  and END of a CRE
fdf0: 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
fe00: 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ement..**.** {H1
fe10: 30 35 31 32 7d 20 49 66 20 61 20 6d 65 6d 6f 72  0512} If a memor
fe20: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
fe30: 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
fe40: 20 61 6e 20 69 6e 76 6f 63 61 74 69 6f 6e 0a 2a   an invocation.*
fe50: 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 5b 73  *          of [s
fe60: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
fe70: 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63  )] or [sqlite3_c
fe80: 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 74 68 65  omplete16()] the
fe90: 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
fea0: 20 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20    routine shall 
feb0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
fec0: 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53  OMEM]..**.** ASS
fed0: 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
fee0: 7b 41 31 30 35 31 32 7d 20 54 68 65 20 69 6e 70  {A10512} The inp
fef0: 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
ff00: 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
ff10: 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
ff20: 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
ff30: 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
ff40: 2a 0a 2a 2a 20 7b 41 31 30 35 31 33 7d 20 54 68  *.** {A10513} Th
ff50: 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
ff60: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
ff70: 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
ff80: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20  -terminated.**  
ff90: 20 20 20 20 20 20 20 20 55 54 46 2d 31 36 20 73          UTF-16 s
ffa0: 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
ffb0: 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
ffc0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
ffd0: 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
ffe0: 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
fff0: 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
10000 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
10010 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10020 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
10030 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
10040 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
10050 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34 30   {H12310} <S4040
10060 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
10070 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
10080 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
10090 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
100a0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a  oked whenever.**
100b0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
100c0 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
100d0 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61  tabase table tha
100e0 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
100f0 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
10100 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a  as locked..**.**
10110 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c   If the busy cal
10120 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
10130 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
10140 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
10150 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
10160 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
10170 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
10180 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
10190 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 20 63  k. If the busy c
101a0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
101b0 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
101c0 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62   callback will b
101d0 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
101e0 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
101f0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
10200 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61  gument to the ha
10210 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
10220 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
10230 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
10240 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
10250 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
10260 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
10270 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
10280 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61  ent to.** the ha
10290 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
102a0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
102b0 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
102c0 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
102d0 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
102e0 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
102f0 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65 0a   event.  If the.
10300 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
10310 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
10320 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
10330 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
10340 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
10350 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
10360 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
10370 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
10380 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
10390 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ed..** If the ca
103a0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
103b0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
103c0 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
103d0 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
103e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
103f0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
10400 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
10410 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
10420 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
10430 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
10440 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
10450 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
10460 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
10470 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
10480 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65 74  n. If SQLite det
10490 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
104a0 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
104b0 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
104c0 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
104d0 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
104e0 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
104f0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
10500 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
10510 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
10520 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
10530 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
10540 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
10550 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
10560 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
10570 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
10580 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
10590 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
105a0 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
105b0 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
105c0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
105d0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
105e0 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
105f0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
10600 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
10610 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
10620 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
10630 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
10640 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
10650 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
10660 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
10670 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
10680 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
10690 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
106a0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
106b0 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
106c0 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
106d0 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
106e0 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
106f0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
10700 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
10710 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
10720 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
10730 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
10740 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
10750 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
10760 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
10770 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
10780 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
10790 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
107a0 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
107b0 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
107c0 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
107d0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
107e0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
107f0 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
10800 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
10810 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
10820 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
10830 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
10840 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
10850 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
10860 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
10870 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
10880 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
10890 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
108a0 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
108b0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
108c0 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
108d0 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
108e0 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
108f0 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
10900 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
10910 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
10920 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
10930 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
10940 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
10950 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
10960 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
10970 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69  * readers.  If i
10980 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
10990 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
109a0 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
109b0 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
109c0 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
109d0 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
109e0 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
109f0 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
10a00 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
10a10 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
10a20 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
10a30 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
10a40 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
10a50 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
10a60 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
10a70 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
10a80 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
10a90 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
10aa0 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74   changes.  See t
10ab0 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f  he.** <a href="/
10ac0 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
10ad0 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
10ae0 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
10af0 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
10b00 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
10b10 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
10b20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
10b30 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
10b40 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20  mportant..**.** 
10b50 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
10b60 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
10b70 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
10b80 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
10b90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10ba0 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
10bb0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
10bc0 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
10bd0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
10be0 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  ler.  Note that 
10bf0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
10c00 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
10c10 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
10c20 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
10c30 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
10c40 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
10c50 2a 0a 2a 2a 20 7b 48 31 32 33 31 31 7d 20 54 68  *.** {H12311} Th
10c60 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  e [sqlite3_busy_
10c70 68 61 6e 64 6c 65 72 28 44 2c 43 2c 41 29 5d 20  handler(D,C,A)] 
10c80 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72  function shall r
10c90 65 70 6c 61 63 65 0a 2a 2a 20 20 20 20 20 20 20  eplace.**       
10ca0 20 20 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b     busy callback
10cb0 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   in the [databas
10cc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
10cd0 77 69 74 68 20 61 20 6e 65 77 0a 2a 2a 20 20 20  with a new.**   
10ce0 20 20 20 20 20 20 20 61 20 6e 65 77 20 62 75 73         a new bus
10cf0 79 20 68 61 6e 64 6c 65 72 20 43 20 61 6e 64 20  y handler C and 
10d00 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
10d10 20 70 6f 69 6e 74 65 72 20 41 2e 0a 2a 2a 0a 2a   pointer A..**.*
10d20 2a 20 7b 48 31 32 33 31 32 7d 20 4e 65 77 6c 79  * {H12312} Newly
10d30 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 62 61   created [databa
10d40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
10d50 73 68 61 6c 6c 20 68 61 76 65 20 61 20 62 75 73  shall have a bus
10d60 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61  y.**          ha
10d70 6e 64 6c 65 72 20 6f 66 20 4e 55 4c 4c 2e 0a 2a  ndler of NULL..*
10d80 2a 0a 2a 2a 20 7b 48 31 32 33 31 34 7d 20 57 68  *.** {H12314} Wh
10d90 65 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 5b  en two or more [
10da0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10db0 69 6f 6e 73 5d 20 73 68 61 72 65 20 61 0a 2a 2a  ions] share a.**
10dc0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
10dd0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
10de0 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e 20  _cache | common 
10df0 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 20 20  cache],.**      
10e00 20 20 20 20 74 68 65 20 62 75 73 79 20 68 61 6e      the busy han
10e10 64 6c 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  dler for the dat
10e20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10e30 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
10e40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
10e50 20 63 61 63 68 65 20 73 68 61 6c 6c 20 62 65 20   cache shall be 
10e60 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
10e70 20 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65 72   cache encounter
10e80 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20  s a lock..**.** 
10e90 7b 48 31 32 33 31 36 7d 20 49 66 20 61 20 62 75  {H12316} If a bu
10ea0 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
10eb0 61 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ack returns zero
10ec0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69 74  , then the SQLit
10ed0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20  e interface.**  
10ee0 20 20 20 20 20 20 20 20 74 68 61 74 20 70 72 6f          that pro
10ef0 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e  voked the lockin
10f00 67 20 65 76 65 6e 74 20 73 68 61 6c 6c 20 72 65  g event shall re
10f10 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
10f20 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31  Y]..**.** {H1231
10f30 38 7d 20 53 51 4c 69 74 65 20 73 68 61 6c 6c 20  8} SQLite shall 
10f40 69 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 73 79  invokes the busy
10f50 20 68 61 6e 64 6c 65 72 20 77 69 74 68 20 74 77   handler with tw
10f60 6f 20 61 72 67 75 6d 65 6e 74 73 20 77 68 69 63  o arguments whic
10f70 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  h.**          ar
10f80 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  e a copy of the 
10f90 70 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 65 64  pointer supplied
10fa0 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61   by the 3rd para
10fb0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  meter to.**     
10fc0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75       [sqlite3_bu
10fd0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61 6e  sy_handler()] an
10fe0 64 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 68 65  d a count of the
10ff0 20 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72   number of prior
11000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76  .**          inv
11010 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
11020 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
11030 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
11040 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41  g event..**.** A
11050 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
11060 2a 20 7b 41 31 32 33 31 39 7d 20 41 20 62 75 73  * {A12319} A bus
11070 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
11080 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
11090 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
110a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
110b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
110c0 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
110d0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
110e0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
110f0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
11100 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
11110 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
11120 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
11130 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
11140 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34 30   Timeout {H12340
11150 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a  } <S40410>.**.**
11160 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65   This routine se
11170 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
11180 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
11190 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
111a0 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
111b0 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
111c0 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
111d0 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
111e0 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a    The handler.**
111f0 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
11200 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
11210 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
11220 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
11230 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
11240 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31  accumulated. {H1
11250 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73 22  2343} After "ms"
11260 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
11270 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
11280 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
11290 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
112a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
112b0 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
112c0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
112d0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
112e0 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61  OCKED]..**.** Ca
112f0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
11300 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
11310 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
11320 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
11330 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
11340 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
11350 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f  *.** There can o
11360 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
11370 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
11380 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
11390 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
113a0 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67  ction] any any g
113b0 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
113c0 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
113d0 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
113e0 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
113f0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
11400 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
11410 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
11420 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
11430 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
11440 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a   is cleared..**.
11450 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
11460 2a 0a 2a 2a 20 7b 48 31 32 33 34 31 7d 20 54 68  *.** {H12341} Th
11470 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  e [sqlite3_busy_
11480 74 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63 74  timeout()] funct
11490 69 6f 6e 20 73 68 61 6c 6c 20 6f 76 65 72 72 69  ion shall overri
114a0 64 65 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20  de any prior.** 
114b0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
114c0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
114d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75  ] or [sqlite3_bu
114e0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65  sy_handler()] se
114f0 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tting.**        
11500 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64    on the same [d
11510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11520 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  on]..**.** {H123
11530 34 33 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70  43} If the 2nd p
11540 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
11550 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
11560 74 28 29 5d 20 69 73 20 6c 65 73 73 20 74 68 61  t()] is less tha
11570 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
11580 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2c 20   equal to zero, 
11590 74 68 65 6e 20 74 68 65 20 62 75 73 79 20 68 61  then the busy ha
115a0 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20 63  ndler shall be c
115b0 6c 65 61 72 65 64 20 73 6f 20 74 68 61 74 0a 2a  leared so that.*
115c0 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 20 73  *          all s
115d0 75 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e  ubsequent lockin
115e0 67 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 69 61  g events immedia
115f0 74 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 51 4c  tely return [SQL
11600 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
11610 20 7b 48 31 32 33 34 34 7d 20 49 66 20 74 68 65   {H12344} If the
11620 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
11630 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  o [sqlite3_busy_
11640 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 61 20  timeout()] is a 
11650 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20  positive.**     
11660 20 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20 74       number N, t
11670 68 65 6e 20 61 20 62 75 73 79 20 68 61 6e 64 6c  hen a busy handl
11680 65 72 20 73 68 61 6c 6c 20 62 65 20 73 65 74 20  er shall be set 
11690 74 68 61 74 20 72 65 70 65 61 74 65 64 6c 79 20  that repeatedly 
116a0 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20  calls.**        
116b0 20 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d    the xSleep() m
116c0 65 74 68 6f 64 20 69 6e 20 74 68 65 20 5b 73 71  ethod in the [sq
116d0 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 20  lite3_vfs | VFS 
116e0 69 6e 74 65 72 66 61 63 65 5d 20 75 6e 74 69 6c  interface] until
116f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 69 74  .**          eit
11700 68 65 72 20 74 68 65 20 6c 6f 63 6b 20 63 6c 65  her the lock cle
11710 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ars or until the
11720 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65 65   cumulative slee
11730 70 20 74 69 6d 65 0a 2a 2a 20 20 20 20 20 20 20  p time.**       
11740 20 20 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b     reported back
11750 20 62 79 20 78 53 6c 65 65 70 28 29 20 65 78 63   by xSleep() exc
11760 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63 6f  eeds N milliseco
11770 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nds..*/.int sqli
11780 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
11790 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
117a0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
117b0 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
117c0 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
117d0 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b 48  nning Queries {H
117e0 31 32 33 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a  12370} <S10000>.
117f0 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
11800 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
11810 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
11820 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
11830 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
11840 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
11850 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
11860 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
11870 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
11880 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
11890 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
118a0 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
118b0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
118c0 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
118d0 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
118e0 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
118f0 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
11900 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
11910 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
11920 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
11930 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
11940 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
11950 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
11960 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
11970 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
11980 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
11990 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
119a0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
119b0 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
119c0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
119d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
119e0 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
119f0 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
11a00 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
11a10 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
11a20 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
11a30 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
11a40 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
11a50 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
11a60 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
11a70 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
11a80 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
11a90 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
11aa0 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
11ab0 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
11ac0 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
11ad0 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
11ae0 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
11af0 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
11b00 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
11b10 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
11b20 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
11b30 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
11b40 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
11b50 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
11b60 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
11b70 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
11b80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11b90 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
11ba0 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
11bb0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
11bc0 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
11bd0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
11be0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
11bf0 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
11c00 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
11c10 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
11c20 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61  .**.** As an exa
11c30 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
11c40 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
11c50 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
11c60 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
11c70 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
11c80 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
11c90 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
11ca0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
11cb0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
11cc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
11cd0 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
11ce0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
11cf0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
11d00 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
11d10 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
11d20 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
11d30 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
11d40 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
11d50 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
11d60 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
11d70 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
11d80 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
11d90 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
11da0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
11db0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
11dc0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
11dd0 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
11de0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
11df0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
11e00 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
11e10 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
11e20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
11e30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
11e40 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
11e50 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
11e60 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
11e70 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
11e80 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
11e90 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
11ea0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
11eb0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
11ec0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
11ed0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
11ee0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
11ef0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
11f00 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
11f10 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
11f20 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
11f30 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
11f40 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
11f50 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
11f60 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
11f70 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
11f80 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
11f90 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
11fa0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
11fb0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
11fc0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
11fd0 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
11fe0 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74  rameter.  It ret
11ff0 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
12000 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
12010 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
12020 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
12030 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
12040 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
12050 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
12060 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  using the result
12070 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70  , it should.** p
12080 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20  ass the pointer 
12090 74 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  to the result ta
120a0 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ble to sqlite3_f
120b0 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
120c0 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
120d0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
120e0 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
120f0 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
12100 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
12110 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
12120 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
12130 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
12140 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
12150 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
12160 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
12170 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
12180 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
12190 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
121a0 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
121b0 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
121c0 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
121d0 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
121e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
121f0 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
12200 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
12210 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
12220 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
12230 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
12240 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
12250 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
12260 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
12270 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
12280 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
12290 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
122a0 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
122b0 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
122c0 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
122d0 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
122e0 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
122f0 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
12300 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
12310 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
12320 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
12330 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
12340 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
12350 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
12360 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
12370 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
12380 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
12390 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  msg()]..**.** IN
123a0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
123b0 7b 48 31 32 33 37 31 7d 20 49 66 20 61 20 5b 73  {H12371} If a [s
123c0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
123d0 28 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f  ()] fails a memo
123e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  ry allocation, t
123f0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
12400 69 74 20 73 68 61 6c 6c 20 66 72 65 65 20 74 68  it shall free th
12410 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 75  e result table u
12420 6e 64 65 72 20 63 6f 6e 73 74 72 75 63 74 69 6f  nder constructio
12430 6e 2c 20 61 62 6f 72 74 20 74 68 65 0a 2a 2a 20  n, abort the.** 
12440 20 20 20 20 20 20 20 20 20 71 75 65 72 79 20 69           query i
12450 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 70 20  n process, skip 
12460 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 71  any subsequent q
12470 75 65 72 69 65 73 2c 20 73 65 74 20 74 68 65 0a  ueries, set the.
12480 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 70 61 7a  **          *paz
12490 52 65 73 75 6c 74 20 6f 75 74 70 75 74 20 70 6f  Result output po
124a0 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e  inter to NULL an
124b0 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
124c0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  _NOMEM]..**.** {
124d0 48 31 32 33 37 33 7d 20 49 66 20 74 68 65 20 70  H12373} If the p
124e0 6e 43 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65  nColumn paramete
124f0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65  r to [sqlite3_ge
12500 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f  t_table()] is no
12510 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  t NULL.**       
12520 20 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73     then a succes
12530 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
12540 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  of [sqlite3_get_
12550 74 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a  table()] shall.*
12560 2a 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65  *          write
12570 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
12580 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
12590 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74            result
125a0 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72   set of the quer
125b0 79 20 69 6e 74 6f 20 2a 70 6e 43 6f 6c 75 6d 6e  y into *pnColumn
125c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 34 7d  ..**.** {H12374}
125d0 20 49 66 20 74 68 65 20 70 6e 52 6f 77 20 70 61   If the pnRow pa
125e0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
125f0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
12600 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20   is not NULL.** 
12610 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 61 20           then a 
12620 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
12630 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
12640 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73  3_get_table()] s
12650 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
12660 20 77 72 69 74 65 73 20 74 68 65 20 6e 75 6d 62   writes the numb
12670 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 74 68  er of rows in th
12680 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
12690 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20  sult set of the 
126a0 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 52 6f  query into *pnRo
126b0 77 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 36  w..**.** {H12376
126c0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
126d0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
126e0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
126f0 29 5d 20 74 68 61 74 20 63 6f 6d 70 75 74 65 73  )] that computes
12700 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 20 72  .**          N r
12710 6f 77 73 20 6f 66 20 72 65 73 75 6c 74 20 77 69  ows of result wi
12720 74 68 20 43 20 63 6f 6c 75 6d 6e 73 20 70 65 72  th C columns per
12730 20 72 6f 77 20 73 68 61 6c 6c 20 6d 61 6b 65 20   row shall make 
12740 2a 70 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 20 20  *pazResult.**   
12750 20 20 20 20 20 20 20 70 6f 69 6e 74 20 74 6f 20         point to 
12760 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
12770 74 65 72 73 20 74 6f 20 28 4e 2b 31 29 2a 43 20  ters to (N+1)*C 
12780 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 74 68  strings where th
12790 65 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20  e first.**      
127a0 20 20 20 20 43 20 73 74 72 69 6e 67 73 20 61 72      C strings ar
127b0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 61  e column names a
127c0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  s obtained from.
127d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
127e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
127f0 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 74  ()] and the rest
12800 20 61 72 65 20 63 6f 6c 75 6d 6e 20 72 65 73 75   are column resu
12810 6c 74 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  lt values.**    
12820 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66        obtained f
12830 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
12840 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
12850 2a 2a 20 7b 48 31 32 33 37 39 7d 20 54 68 65 20  ** {H12379} The 
12860 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 70 61  values in the pa
12870 7a 52 65 73 75 6c 74 20 61 72 72 61 79 20 72 65  zResult array re
12880 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
12890 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a  e3_get_table()].
128a0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
128b0 6c 20 72 65 6d 61 69 6e 20 76 61 6c 69 64 20 75  l remain valid u
128c0 6e 74 69 6c 20 63 6c 65 61 72 65 64 20 62 79 20  ntil cleared by 
128d0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
128e0 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ble()]..**.** {H
128f0 31 32 33 38 32 7d 20 57 68 65 6e 20 61 6e 20 65  12382} When an e
12900 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
12910 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  ng evaluation of
12920 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
12930 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ble()].**       
12940 20 20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20     the function 
12950 73 68 61 6c 6c 20 73 65 74 20 2a 70 61 7a 52 65  shall set *pazRe
12960 73 75 6c 74 20 74 6f 20 4e 55 4c 4c 2c 20 77 72  sult to NULL, wr
12970 69 74 65 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ite an error mes
12980 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  sage.**         
12990 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
129a0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
129b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 6d  te3_malloc()], m
129c0 61 6b 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ake.**          
129d0 2a 2a 70 7a 45 72 72 6d 73 67 20 70 6f 69 6e 74  **pzErrmsg point
129e0 20 74 6f 20 74 68 61 74 20 65 72 72 6f 72 20 6d   to that error m
129f0 65 73 73 61 67 65 2c 20 61 6e 64 20 72 65 74 75  essage, and retu
12a00 72 6e 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  rn a.**         
12a10 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
12a20 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e  ror code]..*/.in
12a30 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
12a40 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
12a50 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
12a60 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
12a70 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
12a80 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
12a90 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
12aa0 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
12ab0 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
12ac0 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
12ad0 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
12ae0 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
12af0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
12b00 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
12b10 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
12b20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
12b30 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
12b40 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
12b50 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
12b60 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
12b70 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
12b80 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
12b90 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
12ba0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
12bb0 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
12bc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
12bd0 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
12be0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
12bf0 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c 53 37 30  ns {H17400} <S70
12c00 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a  000><S20000>.**.
12c10 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
12c20 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73  s are workalikes
12c30 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
12c40 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
12c50 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
12c60 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
12c70 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  brary..**.** The
12c80 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
12c90 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
12ca0 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
12cb0 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
12cc0 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
12cd0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
12ce0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
12cf0 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
12d00 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
12d10 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
12d20 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
12d30 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
12d40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
12d50 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20    Both routines 
12d60 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
12d70 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
12d80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
12d90 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
12da0 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
12db0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
12dc0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
12dd0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c  ng..**.** In sql
12de0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
12df0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
12e00 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
12e10 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
12e20 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
12e30 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
12e40 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
12e50 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
12e60 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
12e70 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
12e80 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
12e90 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
12ea0 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
12eb0 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
12ec0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
12ed0 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
12ee0 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
12ef0 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68   snprintf().  Th
12f00 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
12f10 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
12f20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
12f30 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
12f40 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
12f50 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
12f60 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61  .  Note also tha
12f70 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
12f80 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
12f90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
12fa0 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
12fb0 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
12fc0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
12fd0 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
12fe0 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
12ff0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
13000 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
13010 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
13020 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
13030 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
13040 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
13050 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
13060 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
13070 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
13080 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
13090 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
130a0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
130b0 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73  **.** As long as
130c0 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
130d0 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
130e0 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
130f0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
13100 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
13110 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
13120 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
13130 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  d.  The first.**
13140 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
13150 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
13160 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
13170 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
13180 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
13190 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
131a0 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
131b0 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
131c0 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
131d0 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
131e0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
131f0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
13200 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
13210 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
13220 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
13230 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
13240 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
13250 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
13260 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
13270 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
13280 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
13290 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
132a0 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
132b0 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
132c0 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
132d0 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
132e0 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
132f0 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
13300 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
13310 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e  es a null-termin
13320 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
13330 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
13340 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
13350 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
13360 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
13370 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
13380 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
13390 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
133a0 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e  ral.  By doublin
133b0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
133c0 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
133d0 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
133e0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
133f0 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
13400 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
13410 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
13420 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
13430 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
13440 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
13450 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
13460 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
13470 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
13480 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
13490 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
134a0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
134b0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
134c0 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
134d0 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
134e0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
134f0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
13500 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
13510 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
13520 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
13530 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
13540 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
13550 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
13560 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
13570 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
13580 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
13590 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
135a0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
135b0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
135c0 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
135d0 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
135e0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
135f0 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
13600 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
13610 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
13620 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
13630 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
13640 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
13650 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
13660 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
13670 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
13680 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
13690 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
136a0 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
136b0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
136c0 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
136d0 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
136e0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
136f0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
13700 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
13710 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
13720 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
13730 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
13740 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13750 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
13760 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
13770 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
13780 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
13790 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
137a0 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
137b0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
137c0 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
137d0 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
137e0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
137f0 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f  .** The %Q optio
13800 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
13810 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
13820 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
13830 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
13840 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
13850 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
13860 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
13870 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
13880 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
13890 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
138a0 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
138b0 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
138c0 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
138d0 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
138e0 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  ) in place of th
138f0 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f  e %Q option.  So
13900 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
13910 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
13920 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
13930 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
13940 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
13950 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
13960 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
13970 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
13980 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
13990 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
139a0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
139b0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
139c0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
139d0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
139e0 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
139f0 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
13a00 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
13a10 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
13a20 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
13a30 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
13a40 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
13a50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22  ..**.** The "%z"
13a60 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
13a70 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79  on works exactly
13a80 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68 20   like "%s" with 
13a90 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
13aa0 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
13ab0 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
13ac0 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
13ad0 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
13ae0 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
13af0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
13b00 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
13b10 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49  g. {END}.**.** I
13b20 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
13b30 20 7b 48 31 37 34 30 33 7d 20 20 54 68 65 20 5b   {H17403}  The [
13b40 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
13b50 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
13b60 76 6d 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  vmprintf()] inte
13b70 72 66 61 63 65 73 0a 2a 2a 20 20 20 20 20 20 20  rfaces.**       
13b80 20 20 20 20 72 65 74 75 72 6e 20 65 69 74 68 65      return eithe
13b90 72 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  r pointers to ze
13ba0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
13bb0 46 2d 38 20 73 74 72 69 6e 67 73 20 68 65 6c 64  F-8 strings held
13bc0 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   in.**          
13bd0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
13be0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
13bf0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 4c 4c  alloc()] or NULL
13c00 20 70 6f 69 6e 74 65 72 73 20 69 66 0a 2a 2a 20   pointers if.** 
13c10 20 20 20 20 20 20 20 20 20 20 61 20 63 61 6c 6c            a call
13c20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
13c30 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e 0a 2a 2a  loc()] fails..**
13c40 0a 2a 2a 20 7b 48 31 37 34 30 36 7d 20 20 54 68  .** {H17406}  Th
13c50 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  e [sqlite3_snpri
13c60 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ntf()] interface
13c70 20 77 72 69 74 65 73 20 61 20 7a 65 72 6f 2d 74   writes a zero-t
13c80 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20  erminated.**    
13c90 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72         UTF-8 str
13ca0 69 6e 67 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ing into the buf
13cb0 66 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  fer pointed to b
13cc0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
13cd0 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ameter.**       
13ce0 20 20 20 20 70 72 6f 76 69 64 65 64 20 74 68 61      provided tha
13cf0 74 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  t the first para
13d00 6d 65 74 65 72 20 69 73 20 67 72 65 61 74 65 72  meter is greater
13d10 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a   than zero..**.*
13d20 2a 20 7b 48 31 37 34 30 37 7d 20 20 54 68 65 20  * {H17407}  The 
13d30 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
13d40 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  f()] interface d
13d50 6f 65 73 20 6e 6f 74 20 77 72 69 74 65 20 73 6c  oes not write sl
13d60 6f 74 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ots of.**       
13d70 20 20 20 20 69 74 73 20 6f 75 74 70 75 74 20 62      its output b
13d80 75 66 66 65 72 20 28 74 68 65 20 73 65 63 6f 6e  uffer (the secon
13d90 64 20 70 61 72 61 6d 65 74 65 72 29 20 6f 75 74  d parameter) out
13da0 73 69 64 65 20 74 68 65 20 72 61 6e 67 65 0a 2a  side the range.*
13db0 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 20 30  *           of 0
13dc0 20 74 68 72 6f 75 67 68 20 4e 2d 31 20 28 77 68   through N-1 (wh
13dd0 65 72 65 20 4e 20 69 73 20 74 68 65 20 66 69 72  ere N is the fir
13de0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
13df0 20 20 20 20 20 20 20 20 20 20 20 72 65 67 61 72             regar
13e00 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6c 65 6e  dless of the len
13e10 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
13e20 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  g.**           r
13e30 65 71 75 65 73 74 65 64 20 62 79 20 74 68 65 20  equested by the 
13e40 66 6f 72 6d 61 74 20 73 70 65 63 69 66 69 63 61  format specifica
13e50 74 69 6f 6e 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73  tion..*/.char *s
13e60 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
13e70 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
13e80 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
13e90 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
13ea0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
13eb0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
13ec0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
13ed0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
13ee0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13ef0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
13f00 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20  ation Subsystem 
13f10 7b 48 31 37 33 30 30 7d 20 3c 53 32 30 30 30 30  {H17300} <S20000
13f20 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  >.**.** The SQLi
13f30 74 65 20 63 6f 72 65 20 20 75 73 65 73 20 74 68  te core  uses th
13f40 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
13f50 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
13f60 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
13f70 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
13f80 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
13f90 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
13fa0 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
13fb0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
13fc0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
13fd0 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
13fe0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
13ff0 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
14000 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
14010 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
14020 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
14030 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
14040 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14050 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
14060 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
14070 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
14080 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
14090 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
140a0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
140b0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73  rameter..** If s
140c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
140d0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
140e0 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
140f0 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
14100 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
14110 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68   pointer.  If th
14120 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
14130 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
14140 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
14150 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
14160 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
14170 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
14180 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
14190 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
141a0 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
141b0 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
141c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
141d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
141e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
141f0 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
14200 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
14210 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
14220 65 20 72 65 75 73 65 64 2e 20 20 54 68 65 20 73  e reused.  The s
14230 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
14240 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
14250 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
14260 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
14270 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
14280 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
14290 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
142a0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
142b0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
142c0 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
142d0 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
142e0 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
142f0 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
14300 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
14310 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
14320 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
14330 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
14340 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
14350 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
14360 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
14370 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
14380 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
14390 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
143a0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
143b0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
143c0 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
143d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
143e0 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
143f0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
14400 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
14410 71 6c 69 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a  qlite3_free()..*
14420 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
14430 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
14440 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
14450 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
14460 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
14470 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
14480 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
14490 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
144a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
144b0 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
144c0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
144d0 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
144e0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
144f0 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70    If the first p
14500 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
14510 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
14520 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
14530 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
14540 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
14550 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
14560 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
14570 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
14580 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
14590 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
145a0 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68  lloc()..** If th
145b0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
145c0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
145d0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
145e0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
145f0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
14600 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
14610 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
14620 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
14630 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68  P) where P is th
14640 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
14650 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
14660 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74  lloc()..** sqlit
14670 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
14680 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14690 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
146a0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
146b0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
146c0 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
146d0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
146e0 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  y is unavailable
146f0 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65  ..** If M is the
14700 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
14710 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
14720 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
14730 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
14740 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
14750 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
14760 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
14770 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
14780 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
14790 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70  lloc() and the p
147a0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
147b0 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20  is freed..** If 
147c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
147d0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
147e0 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
147f0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
14800 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
14810 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75   The memory retu
14820 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
14830 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c  malloc() and sql
14840 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
14850 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
14860 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
14870 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
14880 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ry. {END}.**.** 
14890 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c  The default impl
148a0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
148b0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
148c0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73  ion subsystem us
148d0 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63  es.** the malloc
148e0 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  (), realloc() an
148f0 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65  d free() provide
14900 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72  d by the standar
14910 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
14920 7b 48 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72  {H17382} However
14930 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
14940 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
14950 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52  .** SQLITE_MEMOR
14960 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69  Y_SIZE=<i>NNN</i
14970 3e 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  > C preprocessor
14980 20 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69   macro (where <i
14990 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61  >NNN</i>.** is a
149a0 6e 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e  n integer), then
149b0 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 61   SQLite create a
149c0 20 73 74 61 74 69 63 20 61 72 72 61 79 20 6f 66   static array of
149d0 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e   at least.** <i>
149e0 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e  NNN</i> bytes in
149f0 20 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74   size and uses t
14a00 68 61 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c  hat array for al
14a10 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
14a20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
14a30 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e  ation needs. {EN
14a40 44 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d  D}  Additional m
14a50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
14a60 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62  options.** may b
14a70 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
14a80 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  e releases..**.*
14a90 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
14aa0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
14ab0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
14ac0 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
14ad0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
14ae0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
14af0 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
14b00 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
14b10 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
14b20 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
14b30 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
14b40 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
14b50 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
14b60 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
14b70 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
14b80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
14b90 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
14ba0 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73  *.** The Windows
14bb0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
14bc0 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65  yer calls.** the
14bd0 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
14be0 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
14bf0 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
14c00 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
14c10 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
14c20 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
14c30 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
14c40 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
14c50 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
14c60 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
14c70 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
14c80 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
14c90 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
14ca0 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64  ion errors are d
14cb0 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
14cc0 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65  they are reporte
14cd0 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
14ce0 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
14cf0 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
14d00 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
14d10 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
14d20 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
14d30 2a 0a 2a 2a 20 7b 48 31 37 33 30 33 7d 20 20 54  *.** {H17303}  T
14d40 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
14d50 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  oc(N)] interface
14d60 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 20   returns either 
14d70 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
14d80 20 20 20 20 20 20 20 20 20 20 61 20 6e 65 77 6c            a newl
14d90 79 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c  y checked-out bl
14da0 6f 63 6b 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ock of at least 
14db0 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
14dc0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  y.**           t
14dd0 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c  hat is 8-byte al
14de0 69 67 6e 65 64 2c 20 6f 72 20 69 74 20 72 65 74  igned, or it ret
14df0 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74 20  urns NULL if it 
14e00 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 20 20 20  is unable.**    
14e10 20 20 20 20 20 20 20 74 6f 20 66 75 6c 66 69 6c         to fulfil
14e20 6c 20 74 68 65 20 72 65 71 75 65 73 74 2e 0a 2a  l the request..*
14e30 2a 0a 2a 2a 20 7b 48 31 37 33 30 34 7d 20 20 54  *.** {H17304}  T
14e40 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
14e50 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  oc(N)] interface
14e60 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
14e70 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20  pointer if.**   
14e80 20 20 20 20 20 20 20 20 4e 20 69 73 20 6c 65 73          N is les
14e90 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
14ea0 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b  to zero..**.** {
14eb0 48 31 37 33 30 35 7d 20 20 54 68 65 20 5b 73 71  H17305}  The [sq
14ec0 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 20 69  lite3_free(P)] i
14ed0 6e 74 65 72 66 61 63 65 20 72 65 6c 65 61 73 65  nterface release
14ee0 73 20 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f 75  s memory previou
14ef0 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  sly.**          
14f00 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
14f10 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14f20 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
14f30 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20  alloc()],.**    
14f40 20 20 20 20 20 20 20 6d 61 6b 69 6e 67 20 69 74         making it
14f50 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 72   available for r
14f60 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  euse..**.** {H17
14f70 33 30 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20  306}  A call to 
14f80 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 4e 55  [sqlite3_free(NU
14f90 4c 4c 29 5d 20 69 73 20 61 20 68 61 72 6d 6c 65  LL)] is a harmle
14fa0 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
14fb0 7b 48 31 37 33 31 30 7d 20 20 41 20 63 61 6c 6c  {H17310}  A call
14fc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   to [sqlite3_rea
14fd0 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65 71  lloc(0,N)] is eq
14fe0 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61  uivalent to a ca
14ff0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ll.**           
15000 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
15010 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  oc(N)]..**.** {H
15020 31 37 33 31 32 7d 20 20 41 20 63 61 6c 6c 20 74  17312}  A call t
15030 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  o [sqlite3_reall
15040 6f 63 28 50 2c 30 29 5d 20 69 73 20 65 71 75 69  oc(P,0)] is equi
15050 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c  valent to a call
15060 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f  .**           to
15070 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50   [sqlite3_free(P
15080 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31  )]..**.** {H1731
15090 35 7d 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  5}  The SQLite c
150a0 6f 72 65 20 75 73 65 73 20 5b 73 71 6c 69 74 65  ore uses [sqlite
150b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
150c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
150d0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  ,.**           a
150e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  nd [sqlite3_free
150f0 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  ()] for all of i
15100 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ts memory alloca
15110 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20  tion and.**     
15120 20 20 20 20 20 20 64 65 61 6c 6c 6f 63 61 74 69        deallocati
15130 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  on needs..**.** 
15140 7b 48 31 37 33 31 38 7d 20 20 54 68 65 20 5b 73  {H17318}  The [s
15150 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
15160 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
15170 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20  eturns either a 
15180 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
15190 20 20 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20       to a block 
151a0 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d  of checked-out m
151b0 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73  emory of at leas
151c0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
151d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  e.**           t
151e0 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c  hat is 8-byte al
151f0 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c  igned, or a NULL
15200 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
15210 7b 48 31 37 33 32 31 7d 20 20 57 68 65 6e 20 5b  {H17321}  When [
15220 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15230 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20  P,N)] returns a 
15240 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
15250 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20  , it first.**   
15260 20 20 20 20 20 20 20 20 63 6f 70 69 65 73 20 74          copies t
15270 68 65 20 66 69 72 73 74 20 4b 20 62 79 74 65 73  he first K bytes
15280 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d   of content from
15290 20 50 20 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c   P into the newl
152a0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  y.**           a
152b0 6c 6c 6f 63 61 74 65 64 20 62 6c 6f 63 6b 2c 20  llocated block, 
152c0 77 68 65 72 65 20 4b 20 69 73 20 74 68 65 20 6c  where K is the l
152d0 65 73 73 65 72 20 6f 66 20 4e 20 61 6e 64 20 74  esser of N and t
152e0 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 20 20  he size of.**   
152f0 20 20 20 20 20 20 20 20 74 68 65 20 62 75 66 66          the buff
15300 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  er P..**.** {H17
15310 33 32 32 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69  322}  When [sqli
15320 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29  te3_realloc(P,N)
15330 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  ] returns a non-
15340 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74  NULL pointer, it
15350 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20   first.**       
15360 20 20 20 20 72 65 6c 65 61 73 65 73 20 74 68 65      releases the
15370 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a   buffer P..**.**
15380 20 7b 48 31 37 33 32 33 7d 20 20 57 68 65 6e 20   {H17323}  When 
15390 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
153a0 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e  (P,N)] returns N
153b0 55 4c 4c 2c 20 74 68 65 20 62 75 66 66 65 72 20  ULL, the buffer 
153c0 50 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  P is.**         
153d0 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f    not modified o
153e0 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  r released..**.*
153f0 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
15400 2a 0a 2a 2a 20 7b 41 31 37 33 35 30 7d 20 20 54  *.** {A17350}  T
15410 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
15420 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
15430 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
15440 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
15450 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 75  .**           mu
15460 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
15470 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
15480 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
15490 20 61 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20   a prior.**     
154a0 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e        invocation
154b0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
154c0 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
154d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
154e0 61 74 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20  at have.**      
154f0 20 20 20 20 20 6e 6f 74 20 79 65 74 20 62 65 65       not yet bee
15500 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
15510 2a 20 7b 41 31 37 33 35 31 7d 20 20 54 68 65 20  * {A17351}  The 
15520 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
15530 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
15540 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
15550 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 62 6c  *           a bl
15560 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
15570 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
15580 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
15590 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
155a0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
155b0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
155c0 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
155d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
155e0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
155f0 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
15600 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
15610 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
15620 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15630 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
15640 72 20 53 74 61 74 69 73 74 69 63 73 20 7b 48 31  r Statistics {H1
15650 37 33 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a 2a  7370} <S30210>.*
15660 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
15670 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
15680 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
15690 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
156a0 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
156b0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
156c0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
156d0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
156e0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
156f0 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
15700 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
15710 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
15720 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
15730 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
15740 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 31 7d  :.**.** {H17371}
15750 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
15760 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
15770 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
15780 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
15790 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
157a0 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
157b0 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
157c0 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
157d0 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  reed)..**.** {H1
157e0 37 33 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  7373} The [sqlit
157f0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
15800 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
15810 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
15820 75 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  um.**          v
15830 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
15840 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
15850 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
15860 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20  ater mark.**    
15870 20 20 20 20 20 20 77 61 73 20 6c 61 73 74 20 72        was last r
15880 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  eset..**.** {H17
15890 33 37 34 7d 20 54 68 65 20 76 61 6c 75 65 73 20  374} The values 
158a0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
158b0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
158c0 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ()] and.**      
158d0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d      [sqlite3_mem
158e0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
158f0 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
15900 72 68 65 61 64 0a 2a 2a 20 20 20 20 20 20 20 20  rhead.**        
15910 20 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74    added by SQLit
15920 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
15930 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
15940 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
15950 2a 20 20 20 20 20 20 20 20 20 20 62 75 74 20 6e  *          but n
15960 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
15970 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
15980 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
15990 69 62 72 61 72 79 0a 2a 2a 20 20 20 20 20 20 20  ibrary.**       
159a0 20 20 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74     routines that
159b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
159c0 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
159d0 0a 2a 2a 20 7b 48 31 37 33 37 35 7d 20 54 68 65  .** {H17375} The
159e0 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
159f0 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
15a00 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
15a10 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20  value of.**     
15a20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65       [sqlite3_me
15a30 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
15a40 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
15a50 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
15a60 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
15a70 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
15a80 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
15a90 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
15aa0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ed.**          b
15ab0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
15ac0 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
15ad0 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
15ae0 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20  r mark.**       
15af0 20 20 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20     prior to the 
15b00 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
15b10 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
15b20 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
15b30 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
15b40 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
15b50 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
15b60 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
15b70 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
15b80 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
15b90 47 65 6e 65 72 61 74 6f 72 20 7b 48 31 37 33 39  Generator {H1739
15ba0 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S20000>.**.*
15bb0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
15bc0 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
15bd0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
15be0 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
15bf0 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
15c00 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
15c10 52 4f 57 49 44 73 20 77 68 65 6e 20 69 6e 73 65  ROWIDs when inse
15c20 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
15c30 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
15c40 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
15c50 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
15c60 70 6f 73 73 69 62 6c 65 20 52 4f 57 49 44 2e 20  possible ROWID. 
15c70 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73   The PRNG is als
15c80 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68  o used for.** th
15c90 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f  e build-in rando
15ca0 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c  m() and randombl
15cb0 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  ob() SQL functio
15cc0 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66  ns.  This interf
15cd0 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70  ace allows.** ap
15ce0 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63  plications to ac
15cf0 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52  cess the same PR
15d00 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72  NG for other pur
15d10 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  poses..**.** A c
15d20 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
15d30 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
15d40 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
15d50 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
15d60 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
15d70 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e  time this routin
15d80 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69  e is invoked (ei
15d90 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
15da0 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70  or by.** the app
15db0 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52  lication) the PR
15dc0 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69  NG is seeded usi
15dd0 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
15de0 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74  tained.** from t
15df0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
15e00 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
15e10 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
15e20 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e  s] object..** On
15e30 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
15e40 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65  invocations, the
15e50 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
15e60 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
15e70 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
15e80 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
15e90 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
15ea0 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
15eb0 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
15ec0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
15ed0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 39 32 7d 20  .**.** {H17392} 
15ee0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e  The [sqlite3_ran
15ef0 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e  domness(N,P)] in
15f00 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20 4e  terface writes N
15f10 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20   bytes of.**    
15f20 20 20 20 20 20 20 68 69 67 68 2d 71 75 61 6c 69        high-quali
15f30 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
15f40 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
15f50 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69   P..*/.void sqli
15f60 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
15f70 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
15f80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15f90 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
15fa0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
15fb0 62 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c  backs {H12500} <
15fc0 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S70100>.**.** Th
15fd0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
15fe0 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65  ters a authorize
15ff0 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
16000 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
16010 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
16020 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
16030 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
16040 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75  ument..** The au
16050 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16060 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
16070 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
16080 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
16090 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
160a0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
160b0 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
160c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
160d0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
160e0 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
160f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16100 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76  e16_v2()].  At v
16110 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
16120 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
16130 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
16140 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
16150 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
16160 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
16170 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
16180 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16190 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
161a0 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
161b0 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
161c0 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72  wed.  The author
161d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
161e0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
161f0 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
16200 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
16210 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
16220 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
16230 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
16240 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
16250 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
16260 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
16270 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
16280 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
16290 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
162a0 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
162b0 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
162c0 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
162d0 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  .  If the author
162e0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
162f0 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
16300 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
16310 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
16320 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
16330 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
16340 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
16350 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
16360 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
16370 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
16380 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
16390 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
163a0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
163b0 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
163c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
163d0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
163e0 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
163f0 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
16400 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
16410 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
16420 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
16430 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
16440 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16450 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
16460 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
16470 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
16480 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
16490 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
164a0 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
164b0 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
164c0 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
164d0 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
164e0 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  er code is [SQLI
164f0 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
16500 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
16510 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
16520 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
16530 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
16540 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
16550 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
16560 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
16570 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
16580 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
16590 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
165a0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
165b0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
165c0 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
165d0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
165e0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
165f0 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
16600 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
16610 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
16620 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
16630 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
16640 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20   a table..**.** 
16650 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
16660 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
16670 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
16680 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
16690 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
166a0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
166b0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
166c0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 54 68  () interface. Th
166d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
166e0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
166f0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
16700 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
16710 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
16720 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
16730 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
16740 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
16750 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68  thorized. The th
16760 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
16770 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
16780 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
16790 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
167a0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
167b0 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
167c0 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
167d0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
167e0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
167f0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
16800 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
16810 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
16820 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
16830 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
16840 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
16850 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
16860 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
16870 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
16880 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
16890 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
168a0 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
168b0 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
168c0 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
168d0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
168e0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
168f0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
16900 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
16910 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
16920 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
16930 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
16940 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
16950 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
16960 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
16970 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
16980 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
16990 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
169a0 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
169b0 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
169c0 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
169d0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
169e0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
169f0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
16a00 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
16a10 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
16a20 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
16a30 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
16a40 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
16a50 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
16a60 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
16a70 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
16a80 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
16a90 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
16aa0 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
16ab0 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
16ac0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
16ad0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
16ae0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
16af0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
16b00 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
16b10 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
16b20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
16b30 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
16b40 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
16b50 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
16b60 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
16b70 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
16b80 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73  ..**.** Only a s
16b90 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
16ba0 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
16bb0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
16bc0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
16bd0 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
16be0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
16bf0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
16c00 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
16c10 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69  evious call.  Di
16c20 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
16c30 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
16c40 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
16c50 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
16c60 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
16c70 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
16c80 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
16c90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16ca0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
16cb0 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
16cc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16cd0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
16ce0 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
16cf0 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
16d00 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
16d10 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
16d20 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
16d30 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  step()]..**.** I
16d40 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
16d50 20 7b 48 31 32 35 30 31 7d 20 54 68 65 20 5b 73   {H12501} The [s
16d60 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
16d70 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20 69 6e  rizer(D,...)] in
16d80 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
16d90 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
16da0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16db0 61 63 6b 20 77 69 74 68 20 64 61 74 61 62 61 73  ack with databas
16dc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  e connection D..
16dd0 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 32 7d 20 54  **.** {H12502} T
16de0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
16df0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
16e00 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
16e10 6e 74 73 20 61 72 65 0a 2a 2a 20 20 20 20 20 20  nts are.**      
16e20 20 20 20 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c      being compil
16e30 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30  ed..**.** {H1250
16e40 33 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  3} If the author
16e50 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
16e60 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 65 20  turns any value 
16e70 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20  other than.**   
16e80 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49         [SQLITE_I
16e90 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
16ea0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
16eb0 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20  DENY], then.**  
16ec0 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
16ed0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
16ee0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
16ef0 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65   call that cause
16f00 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  d.**          th
16f10 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16f20 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61  lback to run sha
16f30 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 0a  ll fail with an.
16f40 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
16f50 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72  ITE_ERROR] error
16f60 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 61 70 70   code and an app
16f70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d  ropriate error m
16f80 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  essage..**.** {H
16f90 31 32 35 30 34 7d 20 57 68 65 6e 20 74 68 65 20  12504} When the 
16fa0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16fb0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
16fc0 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65  ITE_OK], the ope
16fd0 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ration.**       
16fe0 20 20 20 64 65 73 63 72 69 62 65 64 20 69 73 20     described is 
16ff0 70 72 6f 63 65 73 73 65 64 20 6e 6f 72 6d 61 6c  processed normal
17000 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30  ly..**.** {H1250
17010 35 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74 68  5} When the auth
17020 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17030 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
17040 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 20  DENY], the.**   
17050 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
17060 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
17070 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
17080 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
17090 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74  .**          aut
170a0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
170b0 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61   to run shall fa
170c0 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  il.**          w
170d0 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45  ith an [SQLITE_E
170e0 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65  RROR] error code
170f0 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
17100 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  ssage.**        
17110 20 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61    explaining tha
17120 74 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  t access is deni
17130 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30  ed..**.** {H1250
17140 36 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  6} If the author
17150 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32  izer code (the 2
17160 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
17170 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a  the authorizer.*
17180 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
17190 61 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45 5f  ack) is [SQLITE_
171a0 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61 75  READ] and the au
171b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
171c0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  k returns.**    
171d0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47        [SQLITE_IG
171e0 4e 4f 52 45 5d 2c 20 74 68 65 6e 20 74 68 65 20  NORE], then the 
171f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
17200 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
17210 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  d to.**         
17220 20 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20 76   insert a NULL v
17230 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
17240 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
17250 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
17260 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65  e.**          be
17270 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
17280 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
17290 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
172a0 7b 48 31 32 35 30 37 7d 20 49 66 20 74 68 65 20  {H12507} If the 
172b0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20  authorizer code 
172c0 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74  (the 2nd paramet
172d0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
172e0 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  izer.**         
172f0 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e   callback) is an
17300 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ything other tha
17310 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c  n [SQLITE_READ],
17320 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
17330 20 20 61 20 72 65 74 75 72 6e 20 6f 66 20 5b 53    a return of [S
17340 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61  QLITE_IGNORE] ha
17350 73 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63  s the same effec
17360 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  t as [SQLITE_DEN
17370 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31  Y]..**.** {H1251
17380 30 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72  0} The first par
17390 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
173a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
173b0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  k is a copy of.*
173c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74  *          the t
173d0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
173e0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
173f0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
17400 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
17410 2a 20 7b 48 31 32 35 31 31 7d 20 54 68 65 20 73  * {H12511} The s
17420 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17430 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
17440 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
17450 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
17460 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
17470 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
17480 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75  fies the particu
17490 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20  lar action.**   
174a0 20 20 20 20 20 20 20 74 6f 20 62 65 20 61 75 74         to be aut
174b0 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  horized..**.** {
174c0 48 31 32 35 31 32 7d 20 54 68 65 20 74 68 69 72  H12512} The thir
174d0 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
174e0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
174f0 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a  e callback are.*
17500 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
17510 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
17520 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 0a  gs that contain.
17530 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 69  **          addi
17540 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61  tional details a
17550 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
17560 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
17570 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 30 7d  ..**.** {H12520}
17580 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73   Each call to [s
17590 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
175a0 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 72 69 64  rizer()] overrid
175b0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  es.**          a
175c0 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69 6e  ny previously in
175d0 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69 7a  stalled authoriz
175e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32  er..**.** {H1252
175f0 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72  1} A NULL author
17600 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20  izer means that 
17610 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  no authorization
17620 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
17630 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
17640 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 32 7d  ..**.** {H12522}
17650 20 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74   The default aut
17660 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e  horizer is NULL.
17670 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
17680 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
17690 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
176a0 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
176b0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
176c0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
176d0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
176e0 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
176f0 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
17700 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
17710 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
17720 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20 3c 48  odes {H12590} <H
17730 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  12500>.**.** The
17740 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
17750 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
17760 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
17770 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
17780 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
17790 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
177a0 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
177b0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
177c0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
177d0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
177e0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
177f0 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
17800 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
17810 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
17820 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
17830 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
17840 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
17850 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
17860 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17870 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
17880 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
17890 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
178a0 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
178b0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
178c0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
178d0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
178e0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
178f0 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
17900 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
17910 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b  r Action Codes {
17920 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30 30 3e  H12550} <H12500>
17930 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
17940 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
17950 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
17960 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
17970 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
17980 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
17990 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
179a0 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
179b0 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
179c0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
179d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
179e0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
179f0 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
17a00 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
17a10 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
17a20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
17a30 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
17a40 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
17a50 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
17a60 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17a70 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
17a80 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
17a90 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
17aa0 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
17ab0 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
17ac0 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
17ad0 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
17ae0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
17af0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
17b00 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
17b10 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
17b20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
17b30 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
17b40 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
17b50 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
17b60 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
17b70 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
17b80 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
17b90 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
17ba0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
17bb0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
17bc0 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
17bd0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
17be0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
17bf0 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 61 6d  .  The 6th param
17c00 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
17c10 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
17c20 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
17c30 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
17c40 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
17c50 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
17c60 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
17c70 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
17c80 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
17c90 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
17ca0 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
17cb0 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
17cc0 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  code..**.** INVA
17cd0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
17ce0 31 32 35 35 31 7d 20 54 68 65 20 73 65 63 6f 6e  12551} The secon
17cf0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 61  d parameter to a
17d00 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  n.**          [s
17d10 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17d20 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
17d30 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20  er callback] is 
17d40 61 6c 77 61 79 73 20 61 6e 20 69 6e 74 65 67 65  always an intege
17d50 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
17d60 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74  QLITE_COPY | aut
17d70 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 74 68  horizer code] th
17d80 61 74 20 73 70 65 63 69 66 69 65 73 20 77 68 61  at specifies wha
17d90 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  t action.**     
17da0 20 20 20 20 20 69 73 20 62 65 69 6e 67 20 61 75       is being au
17db0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
17dc0 7b 48 31 32 35 35 32 7d 20 54 68 65 20 33 72 64  {H12552} The 3rd
17dd0 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
17de0 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ers to the.**   
17df0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
17e00 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
17e10 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63   authorization c
17e20 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20 20 20  allback].**     
17e30 20 20 20 20 20 77 69 6c 6c 20 62 65 20 70 61 72       will be par
17e40 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
17e50 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
17e60 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ch.**          [
17e70 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75  SQLITE_COPY | au
17e80 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 69  thorizer code] i
17e90 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
17ea0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a  cond parameter..
17eb0 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 33 7d 20 54  **.** {H12553} T
17ec0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
17ed0 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
17ee0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
17ef0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
17f00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17f10 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a  k] is the name.*
17f20 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
17f30 65 20 64 61 74 61 62 61 73 65 20 28 65 78 61 6d  e database (exam
17f40 70 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65  ple: "main", "te
17f50 6d 70 22 2c 20 65 74 63 2e 29 20 69 66 20 61 70  mp", etc.) if ap
17f60 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  plicable..**.** 
17f70 7b 48 31 32 35 35 34 7d 20 54 68 65 20 36 74 68  {H12554} The 6th
17f80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17f90 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
17fa0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17fb0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
17fc0 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20  er callback] is 
17fd0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20  the name.**     
17fe0 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65       of the inne
17ff0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
18000 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
18010 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
18020 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
18030 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
18040 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
18050 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
18060 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
18070 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65            top-le
18080 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
18090 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
180a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
180b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
180c0 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
180d0 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
180e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
180f0 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
18100 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
18110 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
18120 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18130 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18140 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
18150 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
18160 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
18170 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18180 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
18190 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
181a0 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
181b0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
181c0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
181d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
181e0 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
181f0 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
18200 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
18210 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18220 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18230 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
18240 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
18250 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
18260 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
18270 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
18280 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
18290 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
182a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
182b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
182c0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
182d0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
182e0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
182f0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
18300 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18310 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
18320 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
18330 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
18340 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18350 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18360 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
18370 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
18380 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18390 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
183a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
183b0 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
183c0 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
183d0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
183e0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
183f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18400 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
18410 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
18420 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
18430 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18440 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18450 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
18460 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
18470 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
18480 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18490 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
184a0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
184b0 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
184c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
184d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
184e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
184f0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
18500 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
18510 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
18520 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
18530 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18540 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
18550 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
18560 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
18570 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18580 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18590 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
185a0 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
185b0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
185c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
185d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
185e0 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
185f0 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
18600 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
18610 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
18630 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
18640 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
18650 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
18660 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18670 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
18680 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
18690 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
186a0 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
186b0 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
186c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
186d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
186e0 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
186f0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
18700 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
18710 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
18720 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
18730 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
18740 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
18750 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18760 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
18770 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
18780 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  2   /* NULL     
18790 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
187a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
187b0 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
187c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
187d0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
187e0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
187f0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
18800 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
18810 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
18820 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
18830 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18840 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18850 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
18860 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
18870 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
18880 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
18890 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
188a0 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
188b0 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
188c0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
188d0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
188e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
188f0 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
18900 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
18910 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
18920 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18930 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18940 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
18950 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
18960 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18970 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18980 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18990 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
189a0 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
189b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
189c0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
189d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
189e0 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
189f0 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
18a00 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
18a10 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
18a20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18a30 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
18a40 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 46 75        31   /* Fu
18a50 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55  nction Name   NU
18a60 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18a70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18a80 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
18a90 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
18aa0 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
18ab0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18ac0 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
18ad0 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  iling Functions 
18ae0 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34 30 30  {H12280} <S60400
18af0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
18b00 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
18b10 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
18b20 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
18b30 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
18b40 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
18b50 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
18b60 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
18b70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
18b80 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
18b90 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
18ba0 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
18bb0 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
18bc0 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
18bd0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
18be0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
18bf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
18c00 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  ]..** The callba
18c10 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54 46  ck returns a UTF
18c20 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
18c30 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
18c40 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65  t text.** as the
18c50 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
18c60 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
18c70 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63  g.  Additional c
18c80 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a  allbacks occur.*
18c90 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
18ca0 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
18cb0 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
18cc0 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
18cd0 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
18ce0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
18cf0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
18d00 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
18d10 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  r..**.** The cal
18d20 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
18d30 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
18d40 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
18d50 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
18d60 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
18d70 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68  nt finishes.  Th
18d80 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
18d90 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
18da0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
18db0 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
18dc0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
18dd0 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
18de0 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
18df0 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
18e00 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54   to run..**.** T
18e10 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  he sqlite3_profi
18e20 6c 65 28 29 20 41 50 49 20 69 73 20 63 75 72 72  le() API is curr
18e30 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
18e40 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
18e50 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63 74 20  d.** is subject 
18e60 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d  to change or rem
18e70 6f 76 61 6c 20 69 6e 20 61 20 66 75 74 75 72 65  oval in a future
18e80 20 72 65 6c 65 61 73 65 2e 0a 2a 2a 0a 2a 2a 20   release..**.** 
18e90 54 68 65 20 74 72 69 67 67 65 72 20 72 65 70 6f  The trigger repo
18ea0 72 74 69 6e 67 20 66 65 61 74 75 72 65 20 6f 66  rting feature of
18eb0 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
18ec0 61 63 6b 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ack is considere
18ed0 64 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61  d.** experimenta
18ee0 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74  l and is subject
18ef0 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65   to change or re
18f00 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20  moval in future 
18f10 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 20 46 75 74  releases..** Fut
18f20 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
18f30 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
18f40 6f 20 61 64 64 20 6e 65 77 20 74 72 61 63 65 20  o add new trace 
18f50 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6e 76 6f  callback.** invo
18f60 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  cations..**.** I
18f70 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
18f80 20 7b 48 31 32 32 38 31 7d 20 54 68 65 20 63 61   {H12281} The ca
18f90 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
18fa0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73  registered by [s
18fb0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
18fc0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  is.**          w
18fd0 68 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20 73  henever an SQL s
18fe0 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
18ff0 65 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74 65  egins to execute
19000 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
19010 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 69 67   whenever a trig
19020 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20 66  ger subprogram f
19030 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 72  irst begins to r
19040 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  un..**.** {H1228
19050 32 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  2} Each call to 
19060 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
19070 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20  ] overrides the 
19080 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20  previously.**   
19090 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
190a0 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  d trace callback
190b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 33 7d  ..**.** {H12283}
190c0 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63 61   A NULL trace ca
190d0 6c 6c 62 61 63 6b 20 64 69 73 61 62 6c 65 73 20  llback disables 
190e0 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  tracing..**.** {
190f0 48 31 32 32 38 34 7d 20 54 68 65 20 66 69 72 73  H12284} The firs
19100 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
19110 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
19120 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
19130 20 20 20 20 20 20 20 20 20 20 74 68 65 20 70 6f            the po
19140 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
19150 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  the 3rd argument
19160 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
19170 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ce()]..**.** {H1
19180 32 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e 64  2285} The second
19190 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
191a0 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
191b0 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
191c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
191d0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f   UTF-8 string co
191e0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6f 72 69  ntaining the ori
191f0 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20  ginal text.**   
19200 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 53 51         of the SQ
19210 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69  L statement as i
19220 74 20 77 61 73 20 70 61 73 73 65 64 20 69 6e 74  t was passed int
19230 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
19240 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20  re_v2()].**     
19250 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69       or the equi
19260 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51  valent, or an SQ
19270 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61  L comment indica
19280 74 69 6e 67 20 74 68 65 20 62 65 67 69 6e 6e 69  ting the beginni
19290 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ng.**          o
192a0 66 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70  f a trigger subp
192b0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  rogram..**.** {H
192c0 31 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c 62  12287} The callb
192d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
192e0 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69  istered by [sqli
192f0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69  te3_profile()] i
19300 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20  s invoked.**    
19310 20 20 20 20 20 20 61 73 20 65 61 63 68 20 53 51        as each SQ
19320 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
19330 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  shes..**.** {H12
19340 32 38 38 7d 20 54 68 65 20 66 69 72 73 74 20 70  288} The first p
19350 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
19360 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
19370 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
19380 20 20 20 20 20 20 20 20 20 20 74 68 65 20 33 72            the 3r
19390 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
193a0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
193b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  )]..**.** {H1228
193c0 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  9} The second pa
193d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70  rameter to the p
193e0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
193f0 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
19400 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
19410 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
19420 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  at contains the 
19430 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 20 6f 66  complete text of
19440 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
19450 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
19460 73 20 69 74 20 77 61 73 20 70 72 6f 63 65 73 73  s it was process
19470 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ed by [sqlite3_p
19480 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20  repare_v2()].** 
19490 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
194a0 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a  equivalent..**.*
194b0 2a 20 7b 48 31 32 32 39 30 7d 20 54 68 65 20 74  * {H12290} The t
194c0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
194d0 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61  o the profile ca
194e0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73 74  llback is an est
194f0 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  imate.**        
19500 20 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20    of the number 
19510 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f  of nanoseconds o
19520 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
19530 65 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a  e required to.**
19540 20 20 20 20 20 20 20 20 20 20 72 75 6e 20 74 68            run th
19550 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
19560 66 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66 69  from start to fi
19570 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  nish..*/.void *s
19580 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
19590 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
195a0 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
195b0 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
195c0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70  .void *sqlite3_p
195d0 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
195e0 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
195f0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
19600 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
19610 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
19620 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19630 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
19640 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30  allbacks {H12910
19650 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60400>.**.**
19660 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f   This routine co
19670 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62  nfigures a callb
19680 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74  ack function - t
19690 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63  he.** progress c
196a0 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69  allback - that i
196b0 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
196c0 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
196d0 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61  ng.** running ca
196e0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
196f0 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
19700 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a  3_step()] and.**
19710 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
19720 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d  ble()].  An exam
19730 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
19740 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
19750 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
19760 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
19770 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
19780 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  ** If the progre
19790 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
197a0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
197b0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
197c0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
197d0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
197e0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
197f0 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
19800 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
19810 47 55 49 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  GUI dialog box..
19820 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
19830 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 31 7d  :.**.** {H12911}
19840 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
19850 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
19860 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
19870 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a  gress_handler().
19880 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69  **          is i
19890 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
198a0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
198b0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
198c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
198d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
198e0 2a 0a 2a 2a 20 7b 48 31 32 39 31 32 7d 20 54 68  *.** {H12912} Th
198f0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
19900 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
19910 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20  nce for every N 
19920 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20  virtual.**      
19930 20 20 20 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f      machine opco
19940 64 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  des, where N is 
19950 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
19960 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ent to.**       
19970 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
19980 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
19990 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 72 65  ()] call that re
199a0 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20  gistered.**     
199b0 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63       the callbac
199c0 6b 2e 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73  k.  If N is less
199d0 20 74 68 61 6e 20 31 2c 20 73 71 6c 69 74 65 33   than 1, sqlite3
199e0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
199f0 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r().**          
19a00 61 63 74 73 20 61 73 20 69 66 20 61 20 4e 55 4c  acts as if a NUL
19a10 4c 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  L progress handl
19a20 65 72 20 68 61 64 20 62 65 65 6e 20 73 70 65 63  er had been spec
19a30 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ified..**.** {H1
19a40 32 39 31 33 7d 20 54 68 65 20 70 72 6f 67 72 65  2913} The progre
19a50 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 74 73 65  ss callback itse
19a60 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69 65 64  lf is identified
19a70 20 62 79 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   by the third.**
19a80 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65            argume
19a90 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72  nt to sqlite3_pr
19aa0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
19ab0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 34 7d  ..**.** {H12914}
19ac0 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   The fourth argu
19ad0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
19ae0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
19af0 28 29 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20  () is a.**      
19b00 20 20 20 20 76 6f 69 64 20 70 6f 69 6e 74 65 72      void pointer
19b10 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 70   passed to the p
19b20 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
19b30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
19b40 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20  ction each time 
19b50 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  it is invoked..*
19b60 2a 0a 2a 2a 20 7b 48 31 32 39 31 35 7d 20 49 66  *.** {H12915} If
19b70 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
19b80 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 73 75  te3_step()] resu
19b90 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74 68 61  lts in fewer tha
19ba0 6e 20 4e 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 20  n N opcodes.**  
19bb0 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 65 78          being ex
19bc0 65 63 75 74 65 64 2c 20 74 68 65 6e 20 74 68 65  ecuted, then the
19bd0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
19be0 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f  ck is never invo
19bf0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ked..**.** {H129
19c00 31 36 7d 20 45 76 65 72 79 20 63 61 6c 6c 20 74  16} Every call t
19c10 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  o [sqlite3_progr
19c20 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a  ess_handler()].*
19c30 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72 77  *          overw
19c40 72 69 74 65 73 20 61 6e 79 20 70 72 65 76 69 6f  rites any previo
19c50 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 20  usly registered 
19c60 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
19c70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 37 7d  ..**.** {H12917}
19c80 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73   If the progress
19c90 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
19ca0 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e  k is NULL then n
19cb0 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20  o progress.**   
19cc0 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 69         handler i
19cd0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
19ce0 20 7b 48 31 32 39 31 38 7d 20 49 66 20 74 68 65   {H12918} If the
19cf0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
19d00 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  ck returns a res
19d10 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20 30  ult other than 0
19d20 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
19d30 20 20 20 74 68 65 20 62 65 68 61 76 69 6f 72 20     the behavior 
19d40 69 73 20 61 20 69 66 20 5b 73 71 6c 69 74 65 33  is a if [sqlite3
19d50 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 68 61  _interrupt()] ha
19d60 64 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a  d been called..*
19d70 2a 20 20 20 20 20 20 20 20 20 20 3c 53 33 30 35  *          <S305
19d80 30 30 3e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  00>.*/.void sqli
19d90 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
19da0 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
19db0 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
19dc0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
19dd0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
19de0 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
19df0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48  se Connection {H
19e00 31 32 37 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a  12700} <S40200>.
19e10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
19e20 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
19e30 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
19e40 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20  e whose name is 
19e50 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20  given by the.** 
19e60 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
19e70 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  t. The filename 
19e80 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
19e90 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
19ea0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
19eb0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
19ec0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
19ed0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
19ee0 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
19ef0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
19f00 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41 20 5b  e3_open16(). A [
19f10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19f20 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
19f30 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
19f40 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
19f50 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
19f60 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
19f70 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
19f80 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
19f90 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
19fa0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
19fb0 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
19fc0 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
19fd0 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
19fe0 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
19ff0 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
1a000 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
1a010 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20  te3].** object. 
1a020 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1a030 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
1a040 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
1a050 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
1a060 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
1a070 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
1a080 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1a090 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1a0a0 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
1a0b0 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
1a0c0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1a0d0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
1a0e0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
1a0f0 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
1a100 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
1a110 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
1a120 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ror..**.** The d
1a130 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
1a140 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
1a150 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
1a160 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  f.** sqlite3_ope
1a170 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
1a180 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  pen_v2() is call
1a190 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
1a1a0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1a1b0 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c  yte order if sql
1a1c0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73  ite3_open16() is
1a1d0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
1a1e0 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
1a1f0 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
1a200 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
1a210 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
1a220 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1a230 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1a240 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
1a250 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
1a260 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
1a270 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
1a280 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
1a290 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
1a2a0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
1a2b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1a2c0 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
1a2d0 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
1a2e0 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
1a2f0 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
1a300 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
1a310 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
1a320 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
1a330 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
1a340 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a350 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20  ion.  The flags 
1a360 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 74 61  parameter can ta
1a370 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
1a380 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
1a390 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
1a3a0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
1a3b0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
1a3c0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
1a3d0 66 6c 61 67 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  flag:.**.** <dl>
1a3e0 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  .** <dt>[SQLITE_
1a3f0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
1a400 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1a410 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1a420 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
1a430 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
1a440 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
1a450 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
1a460 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
1a470 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  urned.</dd>.**.*
1a480 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  * <dt>[SQLITE_OP
1a490 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
1a4a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1a4b0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1a4c0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1a4d0 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
1a4e0 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
1a4f0 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
1a500 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
1a510 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
1a520 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
1a530 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
1a540 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
1a550 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
1a560 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
1a570 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1a580 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
1a590 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1a5a0 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
1a5b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1a5c0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1a5d0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1a5e0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1a5f0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
1a600 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74  nd is creates it
1a610 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
1a620 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
1a630 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
1a640 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
1a650 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
1a660 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1a670 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1a680 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c  n16().</dd>.** <
1a690 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
1a6a0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
1a6b0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1a6c0 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
1a6d0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
1a6e0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1a6f0 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  ve or one of the
1a700 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
1a710 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e  own above combin
1a720 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
1a730 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1a740 54 45 58 5d 20 66 6c 61 67 2c 20 74 68 65 6e 20  TEX] flag, then 
1a750 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1a760 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
1a770 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   If the [SQLITE_
1a780 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
1a790 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
1a7a0 6d 75 74 65 78 65 73 20 6f 6e 20 74 68 65 0a 2a  mutexes on the.*
1a7b0 2a 20 6f 70 65 6e 65 64 20 5b 64 61 74 61 62 61  * opened [databa
1a7c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1a7d0 72 65 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  re disabled and 
1a7e0 74 68 65 20 61 70 70 6c 69 61 74 69 6f 6e 20 6d  the appliation m
1a7f0 75 73 74 0a 2a 2a 20 69 6e 73 75 72 65 20 74 68  ust.** insure th
1a800 61 74 20 61 63 63 65 73 73 20 74 6f 20 74 68 65  at access to the
1a810 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a820 63 74 69 6f 6e 5d 20 61 6e 64 20 69 74 73 20 61  ction] and its a
1a830 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 5b 70 72  ssociated.** [pr
1a840 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1a850 73 5d 20 69 73 20 73 65 72 69 61 6c 69 7a 65 64  s] is serialized
1a860 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
1a870 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
1a880 67 0a 2a 2a 20 69 73 20 74 68 65 20 64 65 66 61  g.** is the defa
1a890 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20  ult behavior is 
1a8a0 53 51 4c 69 74 65 20 69 73 20 63 6f 6e 66 69 67  SQLite is config
1a8b0 75 72 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ured using the.*
1a8c0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
1a8d0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 20 6f 72  _MULTITHREAD] or
1a8e0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1a8f0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 70  SINGLETHREAD] op
1a900 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  tions.** to [sql
1a910 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 20  ite3_config()]. 
1a920 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
1a930 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
1a940 6f 6e 6c 79 20 6d 61 6b 65 73 20 61 0a 2a 2a 20  only makes a.** 
1a950 64 69 66 66 65 72 65 6e 63 65 20 77 68 65 6e 20  difference when 
1a960 53 51 4c 69 74 65 20 69 73 20 69 6e 20 69 74 73  SQLite is in its
1a970 20 64 65 66 61 75 6c 74 20 5b 53 51 4c 49 54 45   default [SQLITE
1a980 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
1a990 45 44 5d 20 6d 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  ED] mode..**.** 
1a9a0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1a9b0 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
1a9c0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1a9d0 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
1a9e0 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
1a9f0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1aa00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  e connection.  T
1aa10 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
1aa20 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
1aa30 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
1aa40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1aa50 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
1aa60 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1aa70 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
1aa80 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
1aa90 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
1aaa0 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
1aab0 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
1aac0 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
1aad0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
1aae0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
1aaf0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1ab00 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
1ab10 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
1ab20 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
1ab30 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
1ab40 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
1ab50 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
1ab60 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
1ab70 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
1ab80 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
1ab90 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
1aba0 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
1abb0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1abc0 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
1abd0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1abe0 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20 70  created.  This p
1abf0 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
1ac00 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
1ac10 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
1ac20 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
1ac30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ac40 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
1ac50 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
1ac60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1ac70 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1ac80 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1ac90 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
1aca0 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
1acb0 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
1acc0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
1acd0 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
1ace0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1acf0 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
1ad00 20 75 73 65 2e 20 20 49 66 20 74 68 65 20 66 6f   use.  If the fo
1ad10 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
1ad20 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1ad30 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
1ad40 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1ad50 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
1ad60 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
1ad70 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
1ad80 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
1ad90 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
1ada0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1adb0 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
1adc0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1add0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
1ade0 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
1adf0 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
1ae00 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
1ae10 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
1ae20 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
1ae30 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
1ae40 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
1ae50 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
1ae60 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
1ae70 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
1ae80 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
1ae90 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
1aea0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
1aeb0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1aec0 2a 0a 2a 2a 20 7b 48 31 32 37 30 31 7d 20 54 68  *.** {H12701} Th
1aed0 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
1aee0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1aef0 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20  n16()], and.**  
1af00 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1af10 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
1af20 72 66 61 63 65 73 20 63 72 65 61 74 65 20 61 20  rfaces create a 
1af30 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
1af40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1af50 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
1af60 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
1af70 20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66    the database f
1af80 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  ile given in the
1af90 69 72 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ir first paramet
1afa0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30  er..**.** {H1270
1afb0 32 7d 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  2} The filename 
1afc0 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
1afd0 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
1afe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
1aff0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1b000 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  ] and [sqlite3_o
1b010 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61 73  pen_v2()] and as
1b020 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20   UTF-16.**      
1b030 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76      in the nativ
1b040 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72  e byte order for
1b050 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1b060 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ()]..**.** {H127
1b070 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  03} A successful
1b080 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1b090 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1b0a0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1b0b0 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
1b0c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
1b0d0 6e 5f 76 32 28 29 5d 20 77 72 69 74 65 73 20 61  n_v2()] writes a
1b0e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
1b0f0 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  w.**          [d
1b100 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b110 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a  on] into *ppDb..
1b120 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 34 7d 20 54  **.** {H12704} T
1b130 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
1b140 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1b150 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
1b160 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1b170 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
1b180 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 5b  erfaces return [
1b190 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20  SQLITE_OK] upon 
1b1a0 73 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20  success,.**     
1b1b0 20 20 20 20 20 6f 72 20 61 6e 20 61 70 70 72 6f       or an appro
1b1c0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
1b1d0 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a  de] on failure..
1b1e0 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 36 7d 20 54  **.** {H12706} T
1b1f0 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74 20  he default text 
1b200 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e  encoding for a n
1b210 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65 61  ew database crea
1b220 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ted using.**    
1b230 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
1b240 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  pen()] or [sqlit
1b250 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69  e3_open_v2()] wi
1b260 6c 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a  ll be UTF-8..**.
1b270 2a 2a 20 7b 48 31 32 37 30 37 7d 20 54 68 65 20  ** {H12707} The 
1b280 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63  default text enc
1b290 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20  oding for a new 
1b2a0 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64  database created
1b2b0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
1b2c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
1b2d0 31 36 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54  16()] will be UT
1b2e0 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  F-16..**.** {H12
1b2f0 37 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  709} The [sqlite
1b300 33 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74  3_open(F,D)] int
1b310 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61  erface is equiva
1b320 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20  lent to.**      
1b330 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
1b340 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77  n_v2(F,D,G,0)] w
1b350 68 65 72 65 20 74 68 65 20 47 20 70 61 72 61 6d  here the G param
1b360 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20  eter is.**      
1b370 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e      [SQLITE_OPEN
1b380 5f 52 45 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c  _READWRITE]|[SQL
1b390 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1b3a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 31 7d  ..**.** {H12711}
1b3b0 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
1b3c0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1b3d0 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29  open_v2(F,D,G,V)
1b3e0 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a  ] contains the.*
1b3f0 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76  *          bit v
1b400 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  alue [SQLITE_OPE
1b410 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e  N_READONLY] then
1b420 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1b430 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20   opened.**      
1b440 20 20 20 20 66 6f 72 20 72 65 61 64 69 6e 67 20      for reading 
1b450 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  only..**.** {H12
1b460 37 31 32 7d 20 49 66 20 74 68 65 20 47 20 70 61  712} If the G pa
1b470 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1b480 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
1b490 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74  G,V)] contains t
1b4a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
1b4b0 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
1b4c0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1b4d0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1b4e0 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20  se is opened.** 
1b4f0 20 20 20 20 20 20 20 20 20 72 65 61 64 69 6e 67           reading
1b500 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
1b510 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72  possible, or for
1b520 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66   reading only if
1b530 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1b540 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
1b550 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
1b560 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1b570 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 33 7d  ..**.** {H12713}
1b580 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
1b590 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1b5a0 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29  open(v2(F,D,G,V)
1b5b0 5d 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20  ] omits the.**  
1b5c0 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
1b5d0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
1b5e0 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64  REATE] and the d
1b5f0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
1b600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65  .**          pre
1b610 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61  viously exist, a
1b620 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1b630 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ned..**.** {H127
1b640 31 34 7d 20 49 66 20 74 68 65 20 47 20 70 61 72  14} If the G par
1b650 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
1b660 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47  e3_open(v2(F,D,G
1b670 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68  ,V)] contains th
1b680 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
1b690 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
1b6a0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64  OPEN_CREATE] and
1b6b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1b6c0 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20  es not.**       
1b6d0 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78     previously ex
1b6e0 69 73 74 2c 20 74 68 65 6e 20 61 6e 20 61 74 74  ist, then an att
1b6f0 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
1b700 63 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20  create and.**   
1b710 20 20 20 20 20 20 20 69 6e 69 74 69 61 6c 69 7a         initializ
1b720 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  e the database..
1b730 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 37 7d 20 49  **.** {H12717} I
1b740 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  f the filename a
1b750 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
1b760 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1b770 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
1b780 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1b790 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1b7a0 28 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ()] is ":memory:
1b7b0 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61  ", then an priva
1b7c0 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  te,.**          
1b7d0 65 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65  ephemeral, in-me
1b7e0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 73  mory database is
1b7f0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
1b800 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20   connection..** 
1b810 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49           <todo>I
1b820 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  s SQLITE_OPEN_CR
1b830 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e  EATE|SQLITE_OPEN
1b840 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69  _READWRITE requi
1b850 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
1b860 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  in sqlite3_open_
1b870 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  v2()?</todo>.**.
1b880 2a 2a 20 7b 48 31 32 37 31 39 7d 20 49 66 20 74  ** {H12719} If t
1b890 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e  he filename is N
1b8a0 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20  ULL or an empty 
1b8b0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
1b8c0 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20  rivate,.**      
1b8d0 20 20 20 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e      ephemeral on
1b8e0 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
1b8f0 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 0a  ill be created..
1b900 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64  **          <tod
1b910 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e  o>Is SQLITE_OPEN
1b920 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f  _CREATE|SQLITE_O
1b930 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65  PEN_READWRITE re
1b940 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  quired.**       
1b950 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70     in sqlite3_op
1b960 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a  en_v2()?</todo>.
1b970 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 31 7d 20 54  **.** {H12721} T
1b980 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1b990 6e 65 63 74 69 6f 6e 5d 20 63 72 65 61 74 65 64  nection] created
1b9a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   by [sqlite3_ope
1b9b0 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 0a 2a  n_v2(F,D,G,V)].*
1b9c0 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20  *          will 
1b9d0 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
1b9e0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 64 65  _vfs] object ide
1b9f0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 56  ntified by the V
1ba00 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 20   parameter,.**  
1ba10 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 64          or the d
1ba20 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1ba30 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 66 20 56  vfs] object if V
1ba40 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1ba50 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32  er..**.** {H1272
1ba60 33 7d 20 54 77 6f 20 5b 64 61 74 61 62 61 73 65  3} Two [database
1ba70 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69   connections] wi
1ba80 6c 6c 20 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f  ll share a commo
1ba90 6e 20 63 61 63 68 65 20 69 66 20 62 6f 74 68 20  n cache if both 
1baa0 77 65 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  were.**         
1bab0 20 6f 70 65 6e 65 64 20 77 69 74 68 20 74 68 65   opened with the
1bac0 20 73 61 6d 65 20 56 46 53 20 77 68 69 6c 65 20   same VFS while 
1bad0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1bae0 64 65 5d 20 77 61 73 20 65 6e 61 62 6c 65 64 20  de] was enabled 
1baf0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
1bb00 69 66 20 62 6f 74 68 20 66 69 6c 65 6e 61 6d 65  if both filename
1bb10 73 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20  s compare equal 
1bb20 75 73 69 6e 67 20 6d 65 6d 63 6d 70 28 29 20 61  using memcmp() a
1bb30 66 74 65 72 20 68 61 76 69 6e 67 20 62 65 65 6e  fter having been
1bb40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 6f  .**          pro
1bb50 63 65 73 73 65 64 20 62 79 20 74 68 65 20 5b 73  cessed by the [s
1bb60 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 78 46 75  qlite3_vfs | xFu
1bb70 6c 6c 50 61 74 68 6e 61 6d 65 5d 20 6d 65 74 68  llPathname] meth
1bb80 6f 64 20 6f 66 20 74 68 65 20 56 46 53 2e 0a 2a  od of the VFS..*
1bb90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
1bba0 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
1bbb0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1bbc0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1bbd0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1bbe0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1bbf0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1bc00 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1bc10 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1bc20 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
1bc30 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
1bc40 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1bc50 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
1bc60 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
1bc70 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1bc80 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1bc90 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1bca0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
1bcb0 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
1bcc0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1bcd0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1bce0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1bcf0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
1bd00 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1bd10 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1bd20 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
1bd30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1bd40 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
1bd50 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
1bd60 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
1bd70 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
1bd80 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1bd90 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
1bda0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
1bdb0 20 7b 48 31 32 38 30 30 7d 20 3c 53 36 30 32 30   {H12800} <S6020
1bdc0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
1bdd0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
1bde0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1bdf0 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
1be00 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
1be10 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
1be20 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
1be30 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
1be40 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
1be50 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
1be60 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
1be70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1be80 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
1be90 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
1bea0 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
1beb0 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
1bec0 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
1bed0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
1bee0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1bef0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
1bf00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1bf10 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
1bf20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1bf30 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
1bf40 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
1bf50 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
1bf60 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
1bf70 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1bf80 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
1bf90 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74  ely..** Memory t
1bfa0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
1bfb0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
1bfc0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
1bfd0 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
1bfe0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
1bff0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
1c000 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
1c010 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
1c020 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
1c030 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
1c040 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
1c050 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
1c060 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
1c070 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
1c080 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
1c090 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  ctions..**.** If
1c0a0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
1c0b0 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
1c0c0 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
1c0d0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
1c0e0 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
1c0f0 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
1c100 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
1c110 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
1c120 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
1c130 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
1c140 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
1c150 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  et..**.** INVARI
1c160 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
1c170 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  801} The [sqlite
1c180 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e  3_errcode(D)] in
1c190 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1c1a0 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  the numeric.**  
1c1b0 20 20 20 20 20 20 20 20 5b 72 65 73 75 6c 74 20          [result 
1c1c0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
1c1d0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1c1e0 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
1c1f0 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ently.**        
1c200 20 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61    failed interfa
1c210 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  ce call associat
1c220 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
1c230 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c240 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38  ] D..**.** {H128
1c250 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  03} The [sqlite3
1c260 5f 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64 20  _errmsg(D)] and 
1c270 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1c280 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  6(D)].**        
1c290 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74    interfaces ret
1c2a0 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
1c2b0 75 61 67 65 20 74 65 78 74 20 74 68 61 74 20 64  uage text that d
1c2c0 65 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20 20  escribes.**     
1c2d0 20 20 20 20 20 74 68 65 20 65 72 72 6f 72 20 69       the error i
1c2e0 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65 63  n the mostly rec
1c2f0 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74  ently failed int
1c300 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20  erface call,.** 
1c310 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64           encoded
1c320 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
1c330 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
1c340 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b  ctively..**.** {
1c350 48 31 32 38 30 37 7d 20 54 68 65 20 73 74 72 69  H12807} The stri
1c360 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1c370 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1c380 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1c390 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20  errmsg16()].**  
1c3a0 20 20 20 20 20 20 20 20 61 72 65 20 76 61 6c 69          are vali
1c3b0 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  d until the next
1c3c0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
1c3d0 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e call..**.** {H
1c3e0 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f 20  12808} Calls to 
1c3f0 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68 61  API routines tha
1c400 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e 20  t do not return 
1c410 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  an error code.**
1c420 20 20 20 20 20 20 20 20 20 20 28 65 78 61 6d 70            (examp
1c430 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  le: [sqlite3_dat
1c440 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e  a_count()]) do n
1c450 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ot.**          c
1c460 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20  hange the error 
1c470 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67 65 20  code or message 
1c480 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
1c490 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1c4a0 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71  _errcode()], [sq
1c4b0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c  lite3_errmsg()],
1c4c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
1c4d0 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  msg16()]..**.** 
1c4e0 7b 48 31 32 38 30 39 7d 20 49 6e 74 65 72 66 61  {H12809} Interfa
1c4f0 63 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f 74  ces that are not
1c500 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1c510 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 20   a specific.**  
1c520 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
1c530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 65  e connection] (e
1c540 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20 20  xamples:.**     
1c550 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 70       [sqlite3_mp
1c560 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c  rintf()] or [sql
1c570 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
1c580 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20 20  ed_cache()].**  
1c590 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20 63          do not c
1c5a0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
1c5b0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1c5c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1c5d0 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73  3_errcode()], [s
1c5e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1c5f0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  , or [sqlite3_er
1c600 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  rmsg16()]..*/.in
1c610 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
1c620 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1c630 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1c640 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
1c650 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
1c660 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1c670 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
1c680 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1c690 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
1c6a0 65 63 74 20 7b 48 31 33 30 30 30 7d 20 3c 48 31  ect {H13000} <H1
1c6b0 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  3010>.** KEYWORD
1c6c0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
1c6d0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
1c6e0 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
1c6f0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
1c700 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
1c710 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
1c720 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
1c730 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
1c740 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
1c750 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
1c760 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
1c770 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
1c780 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
1c790 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
1c7a0 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
1c7b0 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
1c7c0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
1c7d0 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
1c7e0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1c7f0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
1c800 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
1c810 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
1c820 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
1c830 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
1c840 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
1c850 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
1c860 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
1c870 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
1c880 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
1c890 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
1c8a0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
1c8b0 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
1c8c0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1c8d0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
1c8e0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
1c8f0 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
1c900 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1c910 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
1c920 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
1c930 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
1c940 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
1c950 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
1c960 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
1c970 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1c980 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
1c990 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
1c9a0 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
1c9b0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
1c9c0 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
1c9d0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1c9e0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1c9f0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1ca00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
1ca10 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
1ca20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1ca30 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48 31  -time Limits {H1
1ca40 32 37 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a 2a  2760} <S20600>.*
1ca50 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
1ca60 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
1ca70 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
1ca80 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
1ca90 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
1caa0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
1cab0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
1cac0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
1cad0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
1cae0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1caf0 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
1cb00 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
1cb10 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
1cb20 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1cb30 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
1cb40 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
1cb50 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
1cb60 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
1cb70 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
1cb80 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
1cb90 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
1cba0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
1cbb0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
1cbc0 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 66  onstruct.  The f
1cbd0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1cbe0 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a  the old limit..*
1cbf0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20  *.** If the new 
1cc00 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
1cc10 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
1cc20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
1cc30 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c  ed..** For the l
1cc40 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66  imit category of
1cc50 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59   SQLITE_LIMIT_XY
1cc60 5a 20 74 68 65 72 65 20 69 73 20 61 20 68 61 72  Z there is a har
1cc70 64 20 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64  d upper.** bound
1cc80 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c   set by a compil
1cc90 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63  e-time C preproc
1cca0 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65  essor macro name
1ccb0 64 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a  d SQLITE_MAX_XYZ
1ccc0 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
1ccd0 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
1cce0 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
1ccf0 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d  MAX_".).** Attem
1cd00 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
1cd10 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
1cd20 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
1cd30 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
1cd40 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
1cd50 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c  the hard upper l
1cd60 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20  imit..**.** Run 
1cd70 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
1cd80 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
1cd90 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
1cda0 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
1cdb0 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
1cdc0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
1cdd0 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
1cde0 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
1cdf0 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
1ce00 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
1ce10 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
1ce20 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
1ce30 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
1ce40 77 65 62 62 72 6f 77 73 65 72 20 74 68 61 74 20  webbrowser that 
1ce50 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
1ce60 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
1ce70 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
1ce80 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
1ce90 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
1cea0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
1ceb0 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
1cec0 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
1ced0 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
1cee0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
1cef0 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
1cf00 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
1cf10 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
1cf20 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
1cf30 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
1cf40 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
1cf50 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
1cf60 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
1cf70 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
1cf80 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
1cf90 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
1cfa0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
1cfb0 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
1cfc0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1cfd0 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
1cfe0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
1cff0 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
1d000 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
1d010 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
1d020 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
1d030 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
1d040 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
1d050 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
1d060 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
1d070 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
1d080 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
1d090 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
1d0a0 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
1d0b0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
1d0c0 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ases..**.** INVA
1d0d0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
1d0e0 31 32 37 36 32 7d 20 41 20 73 75 63 63 65 73 73  12762} A success
1d0f0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
1d100 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56  ite3_limit(D,C,V
1d110 29 5d 20 77 68 65 72 65 20 56 20 69 73 0a 2a 2a  )] where V is.**
1d120 20 20 20 20 20 20 20 20 20 20 70 6f 73 69 74 69            positi
1d130 76 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  ve changes the l
1d140 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65  imit on the size
1d150 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20   of construct C 
1d160 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
1d170 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
1d180 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 74 68  nection] D to th
1d190 65 20 6c 65 73 73 65 72 20 6f 66 20 56 20 61 6e  e lesser of V an
1d1a0 64 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  d the hard upper
1d1b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6f 75  .**          bou
1d1c0 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f  nd on the size o
1d1d0 66 20 43 20 74 68 61 74 20 69 73 20 73 65 74 20  f C that is set 
1d1e0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e  at compile-time.
1d1f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 36 7d 20  .**.** {H12766} 
1d200 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
1d210 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69  l to [sqlite3_li
1d220 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72  mit(D,C,V)] wher
1d230 65 20 56 20 69 73 20 6e 65 67 61 74 69 76 65 0a  e V is negative.
1d240 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 65 61 76  **          leav
1d250 65 73 20 74 68 65 20 73 74 61 74 65 20 6f 66 20  es the state of 
1d260 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1d270 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75 6e 63 68  nnection] D unch
1d280 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  anged..**.** {H1
1d290 32 37 36 39 7d 20 41 20 73 75 63 63 65 73 73 66  2769} A successf
1d2a0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1d2b0 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29  te3_limit(D,C,V)
1d2c0 5d 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  ] returns the.**
1d2d0 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
1d2e0 6f 66 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20  of the limit on 
1d2f0 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73  the size of cons
1d300 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a 2a  truct C in the.*
1d310 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
1d320 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1d330 20 44 20 61 73 20 69 74 20 77 61 73 20 70 72 69   D as it was pri
1d340 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 0a  or to the call..
1d350 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
1d360 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
1d370 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
1d380 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1d390 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
1d3a0 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20 7b  mit Categories {
1d3b0 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30 3e  H12790} <H12760>
1d3c0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
1d3d0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
1d3e0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1d3f0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
1d400 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
1d410 61 72 69 6f 75 73 20 61 73 70 65 63 74 73 20 6f  arious aspects o
1d420 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  f a [database co
1d430 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61  nnection].** tha
1d440 74 20 63 61 6e 20 62 65 20 6c 69 6d 69 74 65 64  t can be limited
1d450 20 69 6e 20 73 69 7a 65 20 62 79 20 63 61 6c 6c   in size by call
1d460 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69  s to [sqlite3_li
1d470 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d  mit()]..** The m
1d480 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
1d490 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 61 72  arious limits ar
1d4a0 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  e as follows:.**
1d4b0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
1d4c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
1d4d0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1d4e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
1d4f0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
1d500 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
1d510 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  row.<dd>.**.** <
1d520 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1d530 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
1d540 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1d550 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
1d560 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  SQL statement.</
1d570 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1d580 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1d590 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
1d5a0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1d5b0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
1d5c0 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
1d5d0 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
1d5e0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53  esult set of a S
1d5f0 45 4c 45 43 54 20 6f 72 20 74 68 65 20 6d 61 78  ELECT or the max
1d600 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1d610 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
1d620 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
1d630 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
1d640 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
1d650 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1d660 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
1d670 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1d680 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
1d690 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
1d6a0 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
1d6b0 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  sion.</dd>.**.**
1d6c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1d6d0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1d6e0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
1d6f0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1d700 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
1d710 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
1d720 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
1d730 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1d740 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
1d750 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d760 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1d770 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
1d780 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
1d790 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
1d7a0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1d7b0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
1d7c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1d7d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
1d7e0 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
1d7f0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1d800 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
1d810 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
1d820 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
1d830 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d840 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
1d850 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1d860 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 74 74 61  m number of atta
1d870 63 68 65 64 20 64 61 74 61 62 61 73 65 73 2e 3c  ched databases.<
1d880 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1d890 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
1d8a0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
1d8b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1d8c0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
1d8d0 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
1d8e0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c 49  gument to the LI
1d8f0 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70  KE or.** GLOB op
1d900 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a  erators.</dd>.**
1d910 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1d920 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1d930 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
1d940 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1d950 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73  ber of variables
1d960 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1d970 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a  ment that can.**
1d980 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a   be bound.</dd>.
1d990 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
1d9a0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1d9b0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
1d9c0 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
1d9d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1d9e0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
1d9f0 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
1da00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1da10 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
1da20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
1da30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1da40 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
1da50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
1da60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1da70 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
1da80 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
1da90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1daa0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
1dab0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1dac0 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
1dad0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
1dae0 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
1daf0 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
1db00 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
1db10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1db20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
1db30 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
1db40 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
1db50 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
1db60 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
1db70 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
1db80 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      9../*.** CAP
1db90 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
1dba0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1dbb0 74 20 7b 48 31 33 30 31 30 7d 20 3c 53 31 30 30  t {H13010} <S100
1dbc0 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
1dbd0 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
1dbe0 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
1dbf0 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
1dc00 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
1dc10 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
1dc20 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
1dc30 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
1dc40 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
1dc50 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
1dc60 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1dc70 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
1dc80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1dc90 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
1dca0 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
1dcb0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1dcc0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1dcd0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
1dce0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1dcf0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ()]..**.** The s
1dd00 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
1dd10 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
1dd20 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
1dd30 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
1dd40 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
1dd50 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
1dd60 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1dd70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
1dd80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
1dd90 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
1dda0 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
1ddb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
1ddc0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1ddd0 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
1dde0 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
1ddf0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
1de00 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
1de10 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
1de20 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
1de30 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
1de40 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49  ro terminator. I
1de50 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
1de60 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
1de70 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
1de80 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
1de90 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
1dea0 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20  ql.  When nByte 
1deb0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
1dec0 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
1ded0 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
1dee0 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
1def0 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
1df00 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
1df10 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
1df20 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
1df30 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
1df40 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
1df50 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
1df60 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
1df70 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
1df80 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
1df90 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
1dfa0 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
1dfb0 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
1dfc0 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
1dfd0 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
1dfe0 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
1dff0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
1e000 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1e010 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
1e020 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
1e030 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e  erminator bytes.
1e040 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69  .**.** *pzTail i
1e050 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
1e060 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
1e070 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  e past the end o
1e080 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 53  f the.** first S
1e090 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1e0a0 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
1e0b0 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69  tines only compi
1e0c0 6c 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  le the first.** 
1e0d0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
1e0e0 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
1e0f0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
1e100 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a  o what remains.*
1e110 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  * uncompiled..**
1e120 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c  .** *ppStmt is l
1e130 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
1e140 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
1e150 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e160 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
1e170 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
1e180 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
1e190 20 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   If there is an 
1e1a0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
1e1b0 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
1e1c0 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20  .  If the input 
1e1d0 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
1e1e0 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
1e1f0 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
1e200 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
1e210 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
1e220 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
1e230 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30 31 38 7d 20  LL..** {A13018} 
1e240 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
1e250 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
1e260 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
1e270 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
1e280 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
1e290 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1e2a0 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
1e2b0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
1e2c0 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20   with it..**.** 
1e2d0 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c  On success, [SQL
1e2e0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
1e2f0 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ned, otherwise a
1e300 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
1e310 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1e320 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
1e330 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
1e340 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1e350 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
1e360 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
1e370 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
1e380 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
1e390 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
1e3a0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
1e3b0 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
1e3c0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
1e3d0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
1e3e0 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
1e3f0 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
1e400 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
1e410 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
1e420 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
1e430 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
1e440 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
1e450 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
1e460 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
1e470 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
1e480 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
1e490 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
1e4a0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
1e4b0 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e 74  have a different
1e4c0 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a  ly in two ways:.
1e4d0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1e4e0 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  i>.** If the dat
1e4f0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
1e500 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
1e510 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
1e520 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
1e530 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
1e540 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
1e550 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
1e560 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1e570 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
1e580 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
1e590 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
1e5a0 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65 6d  n.  If the schem
1e5b0 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e  a has changed in
1e5c0 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d  .** a way that m
1e5d0 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d 65  akes the stateme
1e5e0 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c  nt no longer val
1e5f0 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  id, [sqlite3_ste
1e600 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a  p()] will still.
1e610 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
1e620 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20  E_SCHEMA].  But 
1e630 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63  unlike the legac
1e640 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c  y behavior, [SQL
1e650 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a  ITE_SCHEMA] is.*
1e660 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72  * now a fatal er
1e670 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73  ror.  Calling [s
1e680 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e690 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20  2()] again will 
1e6a0 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20  not make the.** 
1e6b0 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20  error go away.  
1e6c0 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74  Note: use [sqlit
1e6d0 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20  e3_errmsg()] to 
1e6e0 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a  find the text.**
1e6f0 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 20   of the parsing 
1e700 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c  error that resul
1e710 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  ts in an [SQLITE
1e720 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e  _SCHEMA] return.
1e730 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
1e740 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20  <li>.** When an 
1e750 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
1e760 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1e770 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
1e780 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
1e790 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
1e7a0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
1e7b0 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54 68 65 20  or codes].  The 
1e7c0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
1e7d0 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
1e7e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
1e7f0 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
1e800 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
1e810 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
1e820 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 77  ode.** and you w
1e830 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
1e840 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
1e850 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
1e860 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  t()] in order.**
1e870 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
1e880 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
1e890 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
1e8a0 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
1e8b0 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
1e8c0 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
1e8d0 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
1e8e0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1e8f0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
1e900 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
1e910 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  >.**.** INVARIAN
1e920 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31  TS:.**.** {H1301
1e930 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1e940 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c  prepare(db,zSql,
1e950 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ...)] and.**    
1e960 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
1e970 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71  repare_v2(db,zSq
1e980 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  l,...)] interfac
1e990 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  es interpret the
1e9a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78  .**          tex
1e9b0 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20  t in their zSql 
1e9c0 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54 46  parameter as UTF
1e9d0 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31  -8..**.** {H1301
1e9e0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
1e9f0 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a 53 71  prepare16(db,zSq
1ea00 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20  l,...)] and.**  
1ea10 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1ea20 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 64 62  _prepare16_v2(db
1ea30 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65  ,zSql,...)] inte
1ea40 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74  rfaces interpret
1ea50 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1ea60 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a   text in their z
1ea70 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73  Sql parameter as
1ea80 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1ea90 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1eaa0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 33 7d  ..**.** {H13013}
1eab0 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
1eac0 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
1ead0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
1eae0 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29  ,zSql,nByte,...)
1eaf0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  ].**          an
1eb00 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 69  d its variants i
1eb10 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
1eb20 2c 20 74 68 65 20 53 51 4c 20 74 65 78 74 20 69  , the SQL text i
1eb30 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  s.**          re
1eb40 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73 20  ad from zSql is 
1eb50 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 66  read up to the f
1eb60 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
1eb70 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ator..**.** {H13
1eb80 30 31 34 7d 20 49 66 20 74 68 65 20 6e 42 79 74  014} If the nByt
1eb90 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  e argument to [s
1eba0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1ebb0 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  2(db,zSql,nByte,
1ebc0 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
1ebd0 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e    and its varian
1ebe0 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ts is non-negati
1ebf0 76 65 2c 20 74 68 65 6e 20 61 74 20 6d 6f 73 74  ve, then at most
1ec00 20 6e 42 79 74 65 73 20 62 79 74 65 73 20 6f 66   nBytes bytes of
1ec10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
1ec20 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66 72   text is read fr
1ec30 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  om zSql..**.** {
1ec40 48 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69  H13015} In [sqli
1ec50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
1ec60 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69  b,zSql,N,P,pzTai
1ec70 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  l)] and its vari
1ec80 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ants.**         
1ec90 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e 70   if the zSql inp
1eca0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
1ecb0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 53   more than one S
1ecc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
1ecd0 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a 54           and pzT
1ece0 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ail is not NULL,
1ecf0 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
1ed00 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
1ed10 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
1ed20 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73    first byte pas
1ed30 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
1ed40 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
1ed50 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a  ment in zSql..**
1ed60 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
1ed70 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69  What does *pzTai
1ed80 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68  l point to if th
1ed90 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65  ere is one state
1eda0 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  ment?</todo>.**.
1edb0 2a 2a 20 7b 48 31 33 30 31 36 7d 20 41 20 73 75  ** {H13016} A su
1edc0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1edd0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ede0 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70  e_v2(db,zSql,N,p
1edf0 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  pStmt,...)].**  
1ee00 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f          or one o
1ee10 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 77  f its variants w
1ee20 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 74  rites into *ppSt
1ee30 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  mt a pointer to 
1ee40 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  a new.**        
1ee50 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
1ee60 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e  ement] or a poin
1ee70 74 65 72 20 74 6f 20 4e 55 4c 4c 20 69 66 20 7a  ter to NULL if z
1ee80 53 71 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  Sql contains.** 
1ee90 20 20 20 20 20 20 20 20 20 6e 6f 74 68 69 6e 67           nothing
1eea0 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74   other than whit
1eeb0 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e  espace or commen
1eec0 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31  ts..**.** {H1301
1eed0 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
1eee0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 6e  prepare_v2()] in
1eef0 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73 20  terface and its 
1ef00 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e 0a  variants return.
1ef10 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
1ef20 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70  ITE_OK] or an ap
1ef30 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
1ef40 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c   code] upon fail
1ef50 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30  ure..**.** {H130
1ef60 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c 69  21} Before [sqli
1ef70 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a  te3_prepare(db,z
1ef80 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d 74  Sql,nByte,ppStmt
1ef90 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74 73  ,pzTail)] or its
1efa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 72  .**          var
1efb0 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61 6e  iants returns an
1efc0 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c 75   error (any valu
1efd0 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
1efe0 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20 20  LITE_OK]),.**   
1eff0 20 20 20 20 20 20 20 74 68 65 79 20 66 69 72 73         they firs
1f000 74 20 73 65 74 20 2a 70 70 53 74 6d 74 20 74 6f  t set *ppStmt to
1f010 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
1f020 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
1f030 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1f040 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1f050 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1f060 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1f070 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1f080 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
1f090 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1f0a0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1f0b0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1f0c0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1f0d0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1f0e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1f0f0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1f100 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1f110 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1f120 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1f130 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1f140 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1f150 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1f160 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1f170 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
1f180 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1f190 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1f1a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1f1b0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
1f1c0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1f1d0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
1f1e0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1f1f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1f200 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1f210 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1f220 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1f230 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1f240 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1f250 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1f260 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
1f270 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1f280 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1f290 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1f2a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1f2b0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
1f2c0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1f2d0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1f2e0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1f2f0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
1f300 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1f310 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
1f320 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1f330 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1f340 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1f350 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1f360 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1f370 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1f380 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1f390 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1f3a0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
1f3b0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1f3c0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1f3d0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1f3e0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
1f3f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1f400 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
1f410 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1f420 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1f430 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1f440 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1f450 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1f460 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1f470 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1f480 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1f490 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1f4a0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1f4b0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1f4c0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1f4d0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1f4e0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1f4f0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1f500 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1f510 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1f520 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1f530 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46  ;../*.** CAPIREF
1f540 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
1f550 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31 33 31  tement SQL {H131
1f560 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a 2a 0a  00} <H13000>.**.
1f570 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1f580 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
1f590 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
1f5a0 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
1f5b0 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
1f5c0 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
1f5d0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
1f5e0 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
1f5f0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
1f600 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
1f610 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
1f620 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1f630 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1f640 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
1f650 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1f660 0a 2a 2a 20 7b 48 31 33 31 30 31 7d 20 49 66 20  .** {H13101} If 
1f670 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1f680 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20  atement] passed 
1f690 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  as the argument 
1f6a0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
1f6b0 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77  sqlite3_sql()] w
1f6c0 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  as compiled usin
1f6d0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
1f6e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1f6f0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
1f700 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f710 36 5f 76 32 28 29 5d 2c 20 74 68 65 6e 20 5b 73  6_v2()], then [s
1f720 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72 65  qlite3_sql()] re
1f730 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
1f740 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61    a pointer to a
1f750 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1f760 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
1f770 6e 67 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  ng a UTF-8 rende
1f780 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
1f790 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
1f7a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1f7b0 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 32 7d 20 49  **.** {H13102} I
1f7c0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
1f7d0 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65  statement] passe
1f7e0 64 20 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e  d as the argumen
1f7f0 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  t to.**         
1f800 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d   [sqlite3_sql()]
1f810 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73   was compiled us
1f820 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1f830 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1f840 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
1f850 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1f860 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74  ()], then [sqlit
1f870 65 33 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e  e3_sql()] return
1f880 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1f890 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 33 7d  ..**.** {H13103}
1f8a0 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75   The string retu
1f8b0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1f8c0 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c 69  _sql(S)] is vali
1f8d0 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20  d until the.**  
1f8e0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
1f8f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
1f900 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20  s deleted using 
1f910 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1f920 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  e(S)]..*/.const 
1f930 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
1f940 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
1f950 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1f960 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
1f970 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
1f980 20 4f 62 6a 65 63 74 20 7b 48 31 35 30 30 30 7d   Object {H15000}
1f990 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59   <S20200>.** KEY
1f9a0 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
1f9b0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
1f9c0 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
1f9d0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
1f9e0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
1f9f0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
1fa00 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
1fa10 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
1fa20 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
1fa30 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
1fa40 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
1fa50 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
1fa60 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
1fa70 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
1fa80 73 2e 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64  s. Values stored
1fa90 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
1faa0 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
1fab0 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
1fac0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
1fad0 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
1fae0 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
1faf0 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
1fb00 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
1fb10 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
1fb20 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
1fb30 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
1fb40 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
1fb50 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
1fb60 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
1fb70 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
1fb80 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
1fb90 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
1fba0 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
1fbb0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1fbc0 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
1fbd0 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
1fbe0 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
1fbf0 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
1fc00 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
1fc10 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
1fc20 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
1fc30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
1fc40 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
1fc50 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
1fc60 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
1fc70 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
1fc80 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
1fc90 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72  s held.  A inter
1fca0 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
1fcb0 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
1fcc0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1fcd0 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
1fce0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
1fcf0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
1fd00 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1fd10 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
1fd20 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
1fd30 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
1fd40 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
1fd50 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1fd60 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
1fd70 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
1fd80 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
1fd90 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
1fda0 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
1fdb0 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
1fdc0 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
1fdd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
1fde0 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
1fdf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
1fe00 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
1fe10 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
1fe20 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
1fe30 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
1fe40 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
1fe50 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1fe60 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
1fe70 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
1fe80 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
1fe90 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
1fea0 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
1feb0 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
1fec0 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
1fed0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
1fee0 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
1fef0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62 65  ction between be
1ff00 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
1ff10 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
1ff20 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
1ff30 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
1ff40 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
1ff50 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
1ff60 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
1ff70 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
1ff80 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
1ff90 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
1ffa0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1ffb0 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
1ffc0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
1ffd0 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
1ffe0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20  otected..** The 
1fff0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
20000 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
20010 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
20020 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
20030 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
20040 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
20050 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
20060 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
20070 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
20080 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
20090 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
200a0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
200b0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
200c0 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
200d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
200e0 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
200f0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
20100 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
20110 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
20120 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
20130 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
20140 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
20150 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
20160 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
20170 62 6a 65 63 74 20 7b 48 31 36 30 30 31 7d 20 3c  bject {H16001} <
20180 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
20190 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
201a0 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
201b0 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
201c0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
201d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
201e0 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65  bject.  A pointe
201f0 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
20200 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
20210 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
20220 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
20230 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
20240 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
20250 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
20260 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
20270 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
20280 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
20290 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
202a0 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
202b0 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
202c0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
202d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
202e0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
202f0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
20300 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
20310 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
20320 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
20330 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
20340 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
20350 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
20360 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
20370 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
20380 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
20390 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
203a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
203b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
203c0 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
203d0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
203e0 65 6e 74 73 20 7b 48 31 33 35 30 30 7d 20 3c 53  ents {H13500} <S
203f0 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  70300>.** KEYWOR
20400 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
20410 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
20420 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
20430 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
20440 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
20450 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
20460 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
20470 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
20480 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20  *.** In the SQL 
20490 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f  strings input to
204a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
204b0 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
204c0 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
204d0 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
204e0 6c 61 63 65 64 20 62 79 20 61 20 70 61 72 61 6d  laced by a param
204f0 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66 20 74  eter in one of t
20500 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a  hese forms:.**.*
20510 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
20520 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
20530 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
20540 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
20550 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
20560 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
20570 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20  parameter forms 
20580 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20  shown above NNN 
20590 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  is an integer li
205a0 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
205b0 56 20 69 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75  V is an alpha-nu
205c0 6d 65 72 69 63 20 70 61 72 61 6d 65 74 65 72 20  meric parameter 
205d0 6e 61 6d 65 2e 20 54 68 65 20 76 61 6c 75 65 73  name. The values
205e0 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
205f0 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
20600 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
20610 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
20620 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
20630 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
20640 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
20650 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
20660 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
20670 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
20680 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
20690 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
206a0 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
206b0 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
206c0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
206d0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
206e0 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
206f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20700 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
20710 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  riants..**.** Th
20720 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
20730 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
20740 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
20750 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
20760 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53  * The leftmost S
20770 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
20780 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
20790 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e   When the same n
207a0 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
207b0 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
207c0 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
207d0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
207e0 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
207f0 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
20800 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
20810 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
20820 2a 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72  ** The index for
20830 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
20840 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
20850 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
20860 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
20870 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
20880 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
20890 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66    The index.** f
208a0 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65  or "?NNN" parame
208b0 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75  ters is the valu
208c0 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65  e of NNN..** The
208d0 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
208e0 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
208f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
20900 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
20910 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
20920 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
20930 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
20940 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54  e: 999)..**.** T
20950 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
20960 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
20970 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
20980 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
20990 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
209a0 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
209b0 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
209c0 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
209d0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
209e0 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
209f0 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
20a00 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
20a10 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
20a20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
20a30 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
20a40 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
20a50 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74  racters..** If t
20a60 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
20a70 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ter is negative,
20a80 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
20a90 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
20aa0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
20ab0 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
20ac0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
20ad0 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  tor..**.** The f
20ae0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
20af0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
20b00 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69  ob(), sqlite3_bi
20b10 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a  nd_text(), and.*
20b20 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
20b30 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73  ext16() is a des
20b40 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
20b50 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
20b60 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
20b70 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
20b80 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
20b90 69 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68  it. If the fifth
20ba0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
20bb0 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
20bc0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
20bd0 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
20be0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
20bf0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
20c00 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
20c10 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
20c20 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
20c30 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49  o be freed..** I
20c40 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
20c50 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
20c60 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
20c70 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
20c80 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
20c90 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
20ca0 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
20cb0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
20cc0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
20cd0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
20ce0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
20cf0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
20d00 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
20d10 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
20d20 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
20d30 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
20d40 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a  ith zeroes.  A z
20d50 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
20d60 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
20d70 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
20d80 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
20d90 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
20da0 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
20db0 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
20dc0 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
20dd0 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
20de0 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
20df0 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
20e00 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
20e10 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
20e20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
20e30 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
20e40 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
20e50 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74  ines..** A negat
20e60 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
20e70 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
20e80 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
20e90 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
20ea0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
20eb0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75  _*() routines mu
20ec0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74  st be called aft
20ed0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
20ee0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e  repare_v2()] (an
20ef0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20  d its variants) 
20f00 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
20f10 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f  t()] and.** befo
20f20 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  re [sqlite3_step
20f30 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73  ()]..** Bindings
20f40 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
20f50 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
20f60 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
20f70 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61  e..** Unbound pa
20f80 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
20f90 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
20fa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
20fb0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
20fc0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
20fd0 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72  cess or an error
20fe0 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74   code if.** anyt
20ff0 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
21000 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d    [SQLITE_RANGE]
21010 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
21020 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
21030 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
21040 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45   range.  [SQLITE
21050 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
21060 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
21070 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54  fails..** [SQLIT
21080 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20  E_MISUSE] might 
21090 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  be returned if t
210a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
210b0 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a  e called on a.**
210c0 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
210d0 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f   that is the wro
210e0 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63  ng state or whic
210f0 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65  h has already be
21100 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a  en finalized..**
21110 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69   Detection of mi
21120 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62  suse is unreliab
21130 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  le.  Application
21140 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70  s should not dep
21150 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45  end.** on SQLITE
21160 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e  _MISUSE returns.
21170 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20    SQLITE_MISUSE 
21180 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69  is intended to i
21190 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c  ndicate a.** a l
211a0 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68  ogic error in th
211b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
211c0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
211d0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
211e0 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20  ** panic rather 
211f0 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49  than return SQLI
21200 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a  TE_MISUSE..**.**
21210 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
21220 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
21230 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
21240 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
21250 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
21260 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
21270 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
21280 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ex()]..**.** INV
21290 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
212a0 48 31 33 35 30 36 7d 20 54 68 65 20 5b 53 51 4c  H13506} The [SQL
212b0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
212c0 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73 20  ler] recognizes 
212d0 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66 6f  tokens of the fo
212e0 72 6d 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rms.**          
212f0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24 56  "?", "?NNN", "$V
21300 56 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e 64  VV", ":VVV", and
21310 20 22 40 56 56 56 22 20 61 73 20 53 51 4c 20 70   "@VVV" as SQL p
21320 61 72 61 6d 65 74 65 72 73 2c 0a 2a 2a 20 20 20  arameters,.**   
21330 20 20 20 20 20 20 20 77 68 65 72 65 20 4e 4e 4e         where NNN
21340 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65   is any sequence
21350 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
21360 64 69 67 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  digits.**       
21370 20 20 20 61 6e 64 20 77 68 65 72 65 20 56 56 56     and where VVV
21380 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65   is any sequence
21390 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
213a0 61 6c 70 68 61 6e 75 6d 65 72 69 63 0a 2a 2a 20  alphanumeric.** 
213b0 20 20 20 20 20 20 20 20 20 63 68 61 72 61 63 74           charact
213c0 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69  ers or "::" opti
213d0 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20  onally followed 
213e0 62 79 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74  by a string cont
213f0 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  aining.**       
21400 20 20 20 6e 6f 20 73 70 61 63 65 73 20 61 6e 64     no spaces and
21410 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69   contained withi
21420 6e 20 70 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a  n parentheses..*
21430 2a 0a 2a 2a 20 7b 48 31 33 35 30 39 7d 20 54 68  *.** {H13509} Th
21440 65 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20  e initial value 
21450 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
21460 74 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ter is NULL..**.
21470 2a 2a 20 7b 48 31 33 35 31 32 7d 20 54 68 65 20  ** {H13512} The 
21480 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 22 20  index of an "?" 
21490 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
214a0 20 6f 6e 65 20 6c 61 72 67 65 72 20 74 68 61 6e   one larger than
214b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
214c0 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f   largest index o
214d0 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  f SQL parameter 
214e0 74 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20  to the left, or 
214f0 31 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  1 if.**         
21500 20 74 68 65 20 22 3f 22 20 69 73 20 74 68 65 20   the "?" is the 
21510 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
21520 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ameter..**.** {H
21530 31 33 35 31 35 7d 20 54 68 65 20 69 6e 64 65 78  13515} The index
21540 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51   of an "?NNN" SQ
21550 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  L parameter is t
21560 68 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a  he integer NNN..
21570 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 38 7d 20 54  **.** {H13518} T
21580 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22  he index of an "
21590 3a 56 56 56 22 2c 20 22 24 56 56 56 22 2c 20 6f  :VVV", "$VVV", o
215a0 72 20 22 40 56 56 56 22 20 53 51 4c 20 70 61 72  r "@VVV" SQL par
215b0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20  ameter is.**    
215c0 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61        the same a
215d0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 6c  s the index of l
215e0 65 66 74 6d 6f 73 74 20 6f 63 63 75 72 72 65 6e  eftmost occurren
215f0 63 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ces of the same.
21600 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61  **          para
21610 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f  meter, or one mo
21620 72 65 20 74 68 61 6e 20 74 68 65 20 6c 61 72 67  re than the larg
21630 65 73 74 20 69 6e 64 65 78 20 6f 76 65 72 20 61  est index over a
21640 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  ll.**          p
21650 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
21660 20 6c 65 66 74 20 69 66 20 74 68 69 73 20 69 73   left if this is
21670 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
21680 72 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  rence.**        
21690 20 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65    of this parame
216a0 74 65 72 2c 20 6f 72 20 31 20 69 66 20 74 68 69  ter, or 1 if thi
216b0 73 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73  s is the leftmos
216c0 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  t parameter..**.
216d0 2a 2a 20 7b 48 31 33 35 32 31 7d 20 54 68 65 20  ** {H13521} The 
216e0 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  [SQL statement c
216f0 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c 73 20 77  ompiler] fails w
21700 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52  ith an [SQLITE_R
21710 41 4e 47 45 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ANGE].**        
21720 20 20 65 72 72 6f 72 20 69 66 20 74 68 65 20 69    error if the i
21730 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
21740 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
21750 20 74 68 61 6e 20 31 0a 2a 2a 20 20 20 20 20 20   than 1.**      
21760 20 20 20 20 6f 72 20 67 72 65 61 74 65 72 20 74      or greater t
21770 68 61 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  han the compile-
21780 74 69 6d 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f  time SQLITE_MAX_
21790 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 0a  VARIABLE_NUMBER.
217a0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61  **          para
217b0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  meter..**.** {H1
217c0 33 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b  3524} Calls to [
217d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
217e0 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  t | sqlite3_bind
217f0 28 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20  (S,N,V,...)].** 
21800 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61           associa
21810 74 65 20 74 68 65 20 76 61 6c 75 65 20 56 20 77  te the value V w
21820 69 74 68 20 61 6c 6c 20 53 51 4c 20 70 61 72 61  ith all SQL para
21830 6d 65 74 65 72 73 20 68 61 76 69 6e 67 20 61 6e  meters having an
21840 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 64  .**          ind
21850 65 78 20 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b  ex of N in the [
21860 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21870 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  nt] S..**.** {H1
21880 33 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b  3527} Calls to [
21890 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
218a0 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  t | sqlite3_bind
218b0 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  (S,N,...)].**   
218c0 20 20 20 20 20 20 20 6f 76 65 72 72 69 64 65 20         override 
218d0 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68  prior calls with
218e0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73   the same values
218f0 20 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a   of S and N..**.
21900 2a 2a 20 7b 48 31 33 35 33 30 7d 20 42 69 6e 64  ** {H13530} Bind
21910 69 6e 67 73 20 65 73 74 61 62 6c 69 73 68 65 64  ings established
21920 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   by [sqlite3_bin
21930 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33  d_text | sqlite3
21940 5f 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a  _bind(S,...)].**
21950 20 20 20 20 20 20 20 20 20 20 70 65 72 73 69 73            persis
21960 74 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74  t across calls t
21970 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
21980 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  (S)]..**.** {H13
21990 35 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  533} In calls to
219a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
219b0 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  lob(S,N,V,L,D)],
219c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
219d0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
219e0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a  S,N,V,L,D)], or.
219f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
21a00 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
21a10 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c  (S,N,V,L,D)] SQL
21a20 69 74 65 20 62 69 6e 64 73 20 74 68 65 20 66 69  ite binds the fi
21a30 72 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20  rst L.**        
21a40 20 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42    bytes of the B
21a50 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 70 6f  LOB or string po
21a60 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2c 20 77  inted to by V, w
21a70 68 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20  hen L.**        
21a80 20 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76    is non-negativ
21a90 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 36  e..**.** {H13536
21aa0 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
21ab0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
21ac0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a  (S,N,V,L,D)] or.
21ad0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
21ae0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
21af0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c  (S,N,V,L,D)] SQL
21b00 69 74 65 20 62 69 6e 64 73 20 63 68 61 72 61 63  ite binds charac
21b10 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
21b20 20 66 72 6f 6d 20 56 20 74 68 72 6f 75 67 68 20   from V through 
21b30 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
21b40 68 61 72 61 63 74 65 72 20 77 68 65 6e 20 4c 20  haracter when L 
21b50 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  is negative..**.
21b60 2a 2a 20 7b 48 31 33 35 33 39 7d 20 49 6e 20 63  ** {H13539} In c
21b70 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
21b80 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56  _bind_blob(S,N,V
21b90 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,L,D)],.**      
21ba0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
21bb0 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
21bc0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
21bd0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
21be0 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c  _text16(S,N,V,L,
21bf0 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68  D)] when D is th
21c00 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20  e special.**    
21c10 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b        constant [
21c20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
21c30 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
21c40 68 61 74 20 74 68 65 20 76 61 6c 75 65 20 56 0a  hat the value V.
21c50 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 68  **          is h
21c60 65 6c 64 20 69 6e 20 73 74 61 74 69 63 20 75 6e  eld in static un
21c70 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 74 68  managed space th
21c80 61 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e  at will not chan
21c90 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  ge.**          d
21ca0 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
21cb0 6d 65 20 6f 66 20 74 68 65 20 62 69 6e 64 69 6e  me of the bindin
21cc0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 32  g..**.** {H13542
21cd0 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
21ce0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
21cf0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
21d00 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
21d10 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
21d20 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
21d30 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
21d40 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
21d50 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44  N,V,L,D)] when D
21d60 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a   is the special.
21d70 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73  **          cons
21d80 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52 41  tant [SQLITE_TRA
21d90 4e 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75  NSIENT], the rou
21da0 74 69 6e 65 20 6d 61 6b 65 73 20 61 0a 2a 2a 20  tine makes a.** 
21db0 20 20 20 20 20 20 20 20 20 70 72 69 76 61 74 65           private
21dc0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 61 6c   copy of the val
21dd0 75 65 20 56 20 62 65 66 6f 72 65 20 69 74 20 72  ue V before it r
21de0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  eturns..**.** {H
21df0 31 33 35 34 35 7d 20 49 6e 20 63 61 6c 6c 73 20  13545} In calls 
21e00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
21e10 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _blob(S,N,V,L,D)
21e20 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
21e30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
21e40 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f  t(S,N,V,L,D)], o
21e50 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
21e60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
21e70 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77  16(S,N,V,L,D)] w
21e80 68 65 6e 20 44 20 69 73 20 61 20 70 6f 69 6e 74  hen D is a point
21e90 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
21ea0 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51    a function, SQ
21eb0 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 61  Lite invokes tha
21ec0 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 64 65  t function to de
21ed0 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20 20  stroy the.**    
21ee0 20 20 20 20 20 20 76 61 6c 75 65 20 56 20 61 66        value V af
21ef0 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
21f00 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 76 61  hed using the va
21f10 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  lue V..**.** {H1
21f20 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3548} In calls t
21f30 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
21f40 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  zeroblob(S,N,V,L
21f50 29 5d 20 74 68 65 20 76 61 6c 75 65 20 62 6f 75  )] the value bou
21f60 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  nd.**          i
21f70 73 20 61 20 42 4c 4f 42 20 6f 66 20 4c 20 62 79  s a BLOB of L by
21f80 74 65 73 2c 20 6f 72 20 61 20 7a 65 72 6f 2d 6c  tes, or a zero-l
21f90 65 6e 67 74 68 20 42 4c 4f 42 20 69 66 20 4c 20  ength BLOB if L 
21fa0 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  is negative..**.
21fb0 2a 2a 20 7b 48 31 33 35 35 31 7d 20 49 6e 20 63  ** {H13551} In c
21fc0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
21fd0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 53 2c 4e 2c  _bind_value(S,N,
21fe0 56 29 5d 20 74 68 65 20 56 20 61 72 67 75 6d 65  V)] the V argume
21ff0 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 20 20 20 20  nt may.**       
22000 20 20 20 62 65 20 65 69 74 68 65 72 20 61 20 5b     be either a [
22010 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
22020 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
22030 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  or an.**        
22040 20 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73    [unprotected s
22050 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
22060 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ject..*/.int sql
22070 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
22080 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
22090 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
220a0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
220b0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
220c0 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
220d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
220e0 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
220f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
22100 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
22110 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
22120 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
22130 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
22140 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
22150 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
22160 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
22170 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
22180 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
22190 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
221a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
221b0 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20  t char*, int n, 
221c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
221d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
221e0 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
221f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
22200 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
22210 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
22220 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
22230 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
22240 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
22250 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
22260 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
22270 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
22280 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
22290 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
222a0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
222b0 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
222c0 73 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 30 33  s {H13600} <S703
222d0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
222e0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
222f0 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
22300 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
22310 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
22320 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
22330 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
22340 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
22350 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
22360 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
22370 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
22380 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
22390 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
223a0 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
223b0 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
223c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
223d0 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
223e0 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
223f0 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
22400 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
22410 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
22420 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
22430 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
22440 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
22450 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
22460 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
22470 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
22480 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
22490 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
224a0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
224b0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
224c0 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a   ?NNN are used,.
224d0 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
224e0 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
224f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
22500 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
22510 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
22520 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
22530 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
22540 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
22550 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
22560 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
22570 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
22580 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36  NTS:.**.** {H136
22590 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
225a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
225b0 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66  count(S)] interf
225c0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
225d0 20 20 20 20 20 20 20 20 74 68 65 20 6c 61 72 67          the larg
225e0 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c  est index of all
225f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
22600 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
22610 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
22620 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20  tement] S, or 0 
22630 69 66 20 53 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  if S contains no
22640 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2e   SQL parameters.
22650 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
22660 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
22670 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
22680 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
22690 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
226a0 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b  Host Parameter {
226b0 48 31 33 36 32 30 7d 20 3c 53 37 30 33 30 30 3e  H13620} <S70300>
226c0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
226d0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
226e0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d  inter to the nam
226f0 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a  e of the n-th.**
22700 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
22710 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
22720 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53  statement]..** S
22730 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
22740 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
22750 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
22760 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
22770 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
22780 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
22790 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
227a0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
227b0 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
227c0 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
227d0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
227e0 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
227f0 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
22800 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
22810 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
22820 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72  me..** Parameter
22830 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
22840 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
22850 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
22860 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
22870 64 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65 72  d are also refer
22880 72 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79  red to as "anony
22890 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
228a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
228b0 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
228c0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
228d0 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
228e0 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20   If the value n 
228f0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
22900 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70  or if the n-th p
22910 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
22920 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
22930 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
22940 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
22950 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
22960 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
22970 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
22980 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
22990 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
229a0 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
229b0 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
229c0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
229d0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
229e0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
229f0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
22a00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
22a10 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
22a20 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
22a30 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
22a40 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
22a50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
22a60 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
22a70 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
22a80 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 32 31  S:.**.** {H13621
22a90 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
22aa0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
22ab0 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  me(S,N)] interfa
22ac0 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
22ad0 20 20 20 20 20 20 20 61 20 55 54 46 2d 38 20 72         a UTF-8 r
22ae0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
22af0 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
22b00 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20  parameter in.** 
22b10 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
22b20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22b30 5d 20 53 20 68 61 76 69 6e 67 20 69 6e 64 65 78  ] S having index
22b40 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20   N, or.**       
22b50 20 20 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65     NULL if there
22b60 20 69 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d   is no SQL param
22b70 65 74 65 72 20 77 69 74 68 20 69 6e 64 65 78 20  eter with index 
22b80 4e 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 20  N or if the.**  
22b90 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
22ba0 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 69  r with index N i
22bb0 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70  s an anonymous p
22bc0 61 72 61 6d 65 74 65 72 20 22 3f 22 2e 0a 2a 2f  arameter "?"..*/
22bd0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
22be0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
22bf0 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
22c00 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
22c10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
22c20 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
22c30 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
22c40 20 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c   Name {H13640} <
22c50 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65  S70300>.**.** Re
22c60 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
22c70 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
22c80 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
22c90 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78  e.  The.** index
22ca0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
22cb0 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
22cc0 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
22cd0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
22ce0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
22cf0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
22d00 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a  d()].  A zero.**
22d10 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
22d20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
22d30 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
22d40 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   The parameter.*
22d50 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
22d60 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
22d70 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
22d80 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
22d90 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
22da0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
22db0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
22dc0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
22dd0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
22de0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
22df0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
22e00 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
22e10 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
22e20 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
22e30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
22e40 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
22e50 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
22e60 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 34 31 7d  :.**.** {H13641}
22e70 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   The [sqlite3_bi
22e80 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
22e90 65 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ex(S,N)] interfa
22ea0 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
22eb0 20 20 20 20 20 20 20 74 68 65 20 69 6e 64 65 78         the index
22ec0 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65   of SQL paramete
22ed0 72 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  r in the [prepar
22ee0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
22ef0 20 20 20 20 20 20 20 20 20 20 53 20 77 68 6f 73            S whos
22f00 65 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20 74  e name matches t
22f10 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  he UTF-8 string 
22f20 4e 2c 20 6f 72 20 30 20 69 66 20 74 68 65 72 65  N, or 0 if there
22f30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
22f40 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74  no match..*/.int
22f50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
22f60 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
22f70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
22f80 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
22f90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22fa0 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
22fb0 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
22fc0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31  ed Statement {H1
22fd0 33 36 36 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3660} <S70300>.*
22fe0 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f  *.** Contrary to
22ff0 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
23000 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
23010 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
23020 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
23030 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
23040 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
23050 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
23060 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65  atement]..** Use
23070 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
23080 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
23090 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
230a0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  LL..**.** INVARI
230b0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
230c0 36 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  661} The [sqlite
230d0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
230e0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
230f0 65 73 65 74 73 20 61 6c 6c 20 53 51 4c 0a 2a 2a  esets all SQL.**
23100 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
23110 74 65 72 20 62 69 6e 64 69 6e 67 73 20 69 6e 20  ter bindings in 
23120 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
23130 61 74 65 6d 65 6e 74 5d 20 53 20 62 61 63 6b 20  atement] S back 
23140 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
23150 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
23160 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
23170 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
23180 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
23190 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
231a0 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 31  esult Set {H1371
231b0 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
231c0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d  * Return the num
231d0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
231e0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
231f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
23200 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
23210 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72  atement]. This r
23220 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
23230 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
23240 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
23250 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
23260 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
23270 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
23280 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  TE])..**.** INVA
23290 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
232a0 31 33 37 31 31 7d 20 54 68 65 20 5b 73 71 6c 69  13711} The [sqli
232b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
232c0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
232d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
232e0 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r of.**         
232f0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
23300 72 65 73 75 6c 74 20 73 65 74 20 67 65 6e 65 72  result set gener
23310 61 74 65 64 20 62 79 20 74 68 65 20 5b 70 72 65  ated by the [pre
23320 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23330 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   S,.**          
23340 6f 72 20 30 20 69 66 20 53 20 64 6f 65 73 20 6e  or 0 if S does n
23350 6f 74 20 67 65 6e 65 72 61 74 65 20 61 20 72 65  ot generate a re
23360 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74  sult set..*/.int
23370 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23380 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
23390 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
233a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
233b0 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
233c0 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 32  esult Set {H1372
233d0 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
233e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
233f0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
23400 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
23410 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
23420 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
23430 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
23440 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
23450 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
23460 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
23470 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
23480 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
23490 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
234a0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
234b0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
234c0 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
234d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
234e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
234f0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
23500 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  g.  The first pa
23510 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
23520 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23530 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
23540 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
23550 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 54  CT] statement. T
23560 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
23570 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
23580 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68  lumn number.  Th
23590 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
235a0 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
235b0 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65  *.** The returne
235c0 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
235d0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
235e0 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
235f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
23600 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
23610 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
23620 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
23630 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
23640 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
23650 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
23660 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
23670 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
23680 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
23690 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
236a0 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
236b0 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
236c0 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
236d0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
236e0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
236f0 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
23700 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
23710 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
23720 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
23730 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f  **.** The name o
23740 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
23750 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
23760 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
23770 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
23780 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
23790 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
237a0 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
237b0 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
237c0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
237d0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
237e0 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
237f0 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
23800 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
23810 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
23820 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
23830 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32  TS:.**.** {H1372
23840 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  1} A successful 
23850 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
23860 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
23870 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20  n_name(S,N)].** 
23880 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
23890 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
238a0 61 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63  ame of the Nth c
238b0 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69  olumn (where 0 i
238c0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
238d0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
238e0 6e 29 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c  n) for the resul
238f0 74 20 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20  t set of the.** 
23900 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
23910 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
23920 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  as a zero-termin
23930 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
23940 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 33  g..**.** {H13723
23950 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
23960 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
23970 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
23980 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a  _name16(S,N)].**
23990 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
239a0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
239b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 20  name of the Nth 
239c0 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20  column (where 0 
239d0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  is.**          t
239e0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
239f0 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 65 73 75  mn) for the resu
23a00 6c 74 20 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a  lt set of the.**
23a10 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
23a20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
23a30 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   as a zero-termi
23a40 6e 61 74 65 64 20 55 54 46 2d 31 36 20 73 74 72  nated UTF-16 str
23a50 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
23a60 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
23a70 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20  te order..**.** 
23a80 7b 48 31 33 37 32 34 7d 20 54 68 65 20 5b 73 71  {H13724} The [sq
23a90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
23aa0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
23ab0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
23ac0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
23ad0 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e  nterfaces return
23ae0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
23af0 69 66 20 74 68 65 79 20 61 72 65 20 75 6e 61 62  if they are unab
23b00 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  le to.**        
23b10 20 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72    allocate memor
23b20 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 69 72 20  y to hold their 
23b30 6e 6f 72 6d 61 6c 20 72 65 74 75 72 6e 20 73 74  normal return st
23b40 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  rings..**.** {H1
23b50 33 37 32 35 7d 20 49 66 20 74 68 65 20 4e 20 70  3725} If the N p
23b60 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
23b70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
23b80 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  (S,N)] or.**    
23b90 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
23ba0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e  olumn_name16(S,N
23bb0 29 5d 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  )] is out of ran
23bc0 67 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  ge, then the.** 
23bd0 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
23be0 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c  ces return a NUL
23bf0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
23c00 20 7b 48 31 33 37 32 36 7d 20 54 68 65 20 73 74   {H13726} The st
23c10 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
23c20 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
23c30 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64  n_name(S,N)] and
23c40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
23c50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
23c60 65 31 36 28 53 2c 4e 29 5d 20 61 72 65 20 76 61  e16(S,N)] are va
23c70 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  lid until the ne
23c80 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  xt.**          c
23c90 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 72 6f  all to either ro
23ca0 75 74 69 6e 65 20 77 69 74 68 20 74 68 65 20 73  utine with the s
23cb0 61 6d 65 20 53 20 61 6e 64 20 4e 20 70 61 72 61  ame S and N para
23cc0 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20  meters.**       
23cd0 20 20 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c     or until [sql
23ce0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
23cf0 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a  ] is called..**.
23d00 2a 2a 20 7b 48 31 33 37 32 37 7d 20 57 68 65 6e  ** {H13727} When
23d10 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
23d20 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
23d30 74 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e  tatement contain
23d40 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  s.**          an
23d50 20 41 53 20 63 6c 61 75 73 65 2c 20 74 68 65 20   AS clause, the 
23d60 6e 61 6d 65 20 6f 66 20 74 68 61 74 20 63 6f 6c  name of that col
23d70 75 6d 6e 20 69 73 20 74 68 65 20 69 64 65 6e 74  umn is the ident
23d80 69 66 69 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ifier.**        
23d90 20 20 74 6f 20 74 68 65 20 72 69 67 68 74 20 6f    to the right o
23da0 66 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64  f the AS keyword
23db0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
23dc0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23dd0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
23de0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
23df0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
23e00 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
23e10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23e20 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
23e30 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
23e40 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
23e50 52 65 73 75 6c 74 20 7b 48 31 33 37 34 30 7d 20  Result {H13740} 
23e60 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10700>.**.** T
23e70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
23e80 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
23e90 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20   determine what 
23ea0 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a  column of what.*
23eb0 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68  * table in which
23ec0 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75   database a resu
23ed0 6c 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  lt of a [SELECT]
23ee0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73   statement comes
23ef0 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61   from..** The na
23f00 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
23f10 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
23f20 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
23f30 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
23f40 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
23f50 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68  F-16 string.  Th
23f60 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
23f70 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
23f80 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
23f90 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
23fa0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
23fb0 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
23fc0 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
23fd0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
23fe0 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
23ff0 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  e..** The return
24000 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
24010 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
24020 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24030 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
24040 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
24050 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
24060 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
24070 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
24080 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
24090 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
240a0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
240b0 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
240c0 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
240d0 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
240e0 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
240f0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
24100 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
24110 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
24120 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c  ment to the foll
24130 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61  owing calls is a
24140 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24150 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20  ment]..** These 
24160 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
24170 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
24180 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  ut the Nth colum
24190 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
241a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
241b0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
241c0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
241d0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49  rgument..**.** I
241e0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
241f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
24200 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
24210 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
24220 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
24230 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
24240 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
24250 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
24260 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
24270 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
24280 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
24290 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
242a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
242b0 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
242c0 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79   Otherwise, they
242d0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
242e0 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
242f0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
24300 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74  .** and column t
24310 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
24320 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
24330 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
24340 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74  * As with all ot
24350 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
24360 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64   those postfixed
24370 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
24380 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
24390 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65  ded strings, the
243a0 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
243b0 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b   return UTF-8. {
243c0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  END}.**.** These
243d0 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
243e0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
243f0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
24400 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
24410 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
24420 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
24430 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
24440 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
24450 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a  **.** {A13751}.*
24460 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
24470 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
24480 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
24490 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
244a0 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
244b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
244c0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
244d0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
244e0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
244f0 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
24500 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
24510 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  TS:.**.** {H1374
24520 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
24530 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
24540 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
24550 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
24560 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
24570 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  the UTF-8 zero-t
24580 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
24590 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
245a0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a  rom which the.**
245b0 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
245c0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
245d0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
245e0 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74  tement] S is ext
245f0 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20  racted,.**      
24600 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74      or NULL if t
24610 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
24620 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
24630 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
24640 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
24650 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
24660 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
24670 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
24680 7b 48 31 33 37 34 32 7d 20 54 68 65 20 5b 73 71  {H13742} The [sq
24690 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
246a0 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c 4e  abase_name16(S,N
246b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
246c0 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
246d0 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
246e0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
246f0 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  rder zero-termin
24700 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
24710 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20   database.**    
24720 20 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68        from which
24730 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
24740 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70  column of the [p
24750 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24760 74 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20  t] S is.**      
24770 20 20 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f      extracted, o
24780 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
24790 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
247a0 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65   a general expre
247b0 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ssion.**        
247c0 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74    or if unable t
247d0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
247e0 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e  y to store the n
247f0 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ame..**.** {H137
24800 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  43} The [sqlite3
24810 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
24820 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  me(S,N)] interfa
24830 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
24840 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
24850 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  e UTF-8 zero-ter
24860 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
24870 74 68 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77  the table from w
24880 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20  hich the.**     
24890 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20       Nth result 
248a0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70  column of the [p
248b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
248c0 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65  t] S is extracte
248d0 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  d,.**          o
248e0 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
248f0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
24900 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65   a general expre
24910 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ssion.**        
24920 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74    or if unable t
24930 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
24940 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e  y to store the n
24950 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ame..**.** {H137
24960 34 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  44} The [sqlite3
24970 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
24980 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  me16(S,N)] inter
24990 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
249a0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
249b0 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
249c0 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72  e byte order zer
249d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
249e0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
249f0 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
24a00 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65  which the Nth re
24a10 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
24a20 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
24a30 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20  tement] S is.** 
24a40 20 20 20 20 20 20 20 20 20 65 78 74 72 61 63 74           extract
24a50 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
24a60 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
24a70 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
24a80 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
24a90 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
24aa0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
24ab0 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
24ac0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
24ad0 7b 48 31 33 37 34 35 7d 20 54 68 65 20 5b 73 71  {H13745} The [sq
24ae0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
24af0 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69  gin_name(S,N)] i
24b00 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24b10 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
24b20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65      the UTF-8 ze
24b30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
24b40 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  me of the table 
24b50 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63  column from whic
24b60 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  h the.**        
24b70 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
24b80 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70  umn of the [prep
24b90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24ba0 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a  S is extracted,.
24bb0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e  **          or N
24bc0 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
24bd0 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20  olumn of S is a 
24be0 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
24bf0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
24c00 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
24c10 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
24c20 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
24c30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 36 7d  ..**.** {H13746}
24c40 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
24c50 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
24c60 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
24c70 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
24c80 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
24c90 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
24ca0 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d  byte order zero-
24cb0 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
24cc0 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
24cd0 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20           column 
24ce0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e  from which the N
24cf0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
24d00 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
24d10 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
24d20 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78  atement] S is ex
24d30 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
24d40 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
24d50 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  mn.**          o
24d60 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
24d70 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69   expression or i
24d80 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
24d90 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  cate memory.**  
24da0 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65          to store
24db0 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
24dc0 20 7b 48 31 33 37 34 38 7d 20 54 68 65 20 72 65   {H13748} The re
24dd0 74 75 72 6e 20 76 61 6c 75 65 73 20 66 72 6f 6d  turn values from
24de0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
24df0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
24e00 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
24e10 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
24e20 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20  erfaces].**     
24e30 20 20 20 20 20 61 72 65 20 76 61 6c 69 64 20 66       are valid f
24e40 6f 72 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  or the lifetime 
24e50 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  of the [prepared
24e60 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20   statement].**  
24e70 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c          or until
24e80 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
24e90 20 63 68 61 6e 67 65 64 20 62 79 20 61 6e 6f 74   changed by anot
24ea0 68 65 72 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  her metadata.** 
24eb0 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
24ec0 63 65 20 63 61 6c 6c 20 66 6f 72 20 74 68 65 20  ce call for the 
24ed0 73 61 6d 65 20 70 72 65 70 61 72 65 64 20 73 74  same prepared st
24ee0 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
24ef0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  mn..**.** ASSUMP
24f00 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
24f10 33 37 35 31 7d 20 49 66 20 74 77 6f 20 6f 72 20  3751} If two or 
24f20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
24f30 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
24f40 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
24f50 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
24f60 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
24f70 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
24f80 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20  aces].**        
24f90 20 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b    for the same [
24fa0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24fb0 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
24fc0 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20  olumn.**        
24fd0 20 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69    at the same ti
24fe0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
24ff0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
25000 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
25010 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
25020 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
25030 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
25040 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
25050 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
25060 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
25070 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
25080 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
25090 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
250a0 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
250b0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
250c0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
250d0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
250e0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
250f0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
25100 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
25110 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
25120 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
25130 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
25140 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
25150 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
25160 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
25170 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25180 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
25190 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
251a0 73 75 6c 74 20 7b 48 31 33 37 36 30 7d 20 3c 53  sult {H13760} <S
251b0 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  10700>.**.** The
251c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
251d0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
251e0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
251f0 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
25200 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
25210 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
25220 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
25230 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
25240 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
25250 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
25260 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
25270 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
25280 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
25290 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
252a0 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
252b0 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
252c0 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20 74   returned.  If t
252d0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
252e0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
252f0 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
25300 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
25310 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
25320 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
25330 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65  ..** The returne
25340 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
25350 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
25360 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f  . {END}.**.** Fo
25370 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
25380 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
25390 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
253a0 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
253b0 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
253c0 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
253d0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
253e0 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
253f0 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
25400 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
25410 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
25420 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
25430 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
25440 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
25450 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
25460 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
25470 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
25480 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
25490 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a   column (i==0)..
254a0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
254b0 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
254c0 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a  me typing.  So j
254d0 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
254e0 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
254f0 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
25500 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
25510 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
25520 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
25530 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
25540 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
25550 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
25560 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
25570 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
25580 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
25590 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
255a0 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61  c.  Type.** is a
255b0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
255c0 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
255d0 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
255e0 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
255f0 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
25600 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  values..**.** IN
25610 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
25620 7b 48 31 33 37 36 31 7d 20 20 41 20 73 75 63 63  {H13761}  A succ
25630 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
25640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
25650 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 72 65  ecltype(S,N)] re
25660 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20  turns a.**      
25670 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
25680 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
25690 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
256a0 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79   declared dataty
256b0 70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  pe.**           
256c0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
256d0 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73  umn that appears
256e0 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   as the Nth colu
256f0 6d 6e 20 28 6e 75 6d 62 65 72 65 64 0a 2a 2a 20  mn (numbered.** 
25700 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 30            from 0
25710 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  ) of the result 
25720 73 65 74 20 74 6f 20 74 68 65 20 5b 70 72 65 70  set to the [prep
25730 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25740 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 32  S..**.** {H13762
25750 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  }  A successful 
25760 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
25770 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
25780 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20  16(S,N)].**     
25790 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
257a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
257b0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
257c0 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67 0a  te order string.
257d0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 6e  **           con
257e0 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c  taining the decl
257f0 61 72 65 64 20 64 61 74 61 74 79 70 65 20 6f 66  ared datatype of
25800 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
25810 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a  n that appears.*
25820 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74  *           as t
25830 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e  he Nth column (n
25840 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20  umbered from 0) 
25850 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
25860 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  t to the.**     
25870 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
25880 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a  statement] S..**
25890 0a 2a 2a 20 7b 48 31 33 37 36 33 7d 20 20 49 66  .** {H13763}  If
258a0 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
258b0 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61 74 65  0 or N is greate
258c0 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  r than or equal 
258d0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  to.**           
258e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
258f0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 5b 70 72  lumns in the [pr
25900 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25910 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] S,.**         
25920 20 20 6f 72 20 69 66 20 74 68 65 20 4e 74 68 20    or if the Nth 
25930 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
25940 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  n expression or 
25950 73 75 62 71 75 65 72 79 20 72 61 74 68 65 72 0a  subquery rather.
25960 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61  **           tha
25970 6e 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  n a table column
25980 2c 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  , or if a memory
25990 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
259a0 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ure.**          
259b0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 65   occurs during e
259c0 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73 69  ncoding conversi
259d0 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  ons, then.**    
259e0 20 20 20 20 20 20 20 63 61 6c 6c 73 20 74 6f 20         calls to 
259f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
25a00 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 6f  decltype(S,N)] o
25a10 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  r.**           [
25a20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
25a30 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 20  ecltype16(S,N)] 
25a40 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a  return NULL..*/.
25a50 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
25a60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
25a70 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
25a80 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
25a90 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
25aa0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
25ab0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
25ac0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25ad0 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
25ae0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31  QL Statement {H1
25af0 33 32 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a  3200} <S10000>.*
25b00 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
25b10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25b20 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
25b30 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
25b40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
25b50 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
25b60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25b70 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
25b80 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
25b90 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
25ba0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
25bb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25bc0 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
25bd0 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
25be0 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
25bf0 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
25c00 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
25c10 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
25c20 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
25c30 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
25c40 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
25c50 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
25c60 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
25c70 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
25c80 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
25c90 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
25ca0 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
25cb0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
25cc0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
25cd0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
25ce0 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
25cf0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
25d00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
25d10 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
25d20 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
25d30 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
25d40 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
25d50 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
25d60 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
25d70 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
25d80 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
25d90 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
25da0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
25db0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c  ..**.** In the l
25dc0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
25dd0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
25de0 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
25df0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
25e00 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
25e10 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
25e20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
25e30 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
25e40 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  E]..** With the 
25e50 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
25e60 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
25e70 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
25e80 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
25e90 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
25ea0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
25eb0 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b  as well..**.** [
25ec0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
25ed0 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
25ee0 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
25ef0 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
25f00 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
25f10 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
25f20 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
25f30 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
25f40 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
25f50 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
25f60 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
25f70 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
25f80 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
25f90 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
25fa0 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
25fb0 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
25fc0 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
25fd0 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a  curs within a.**
25fe0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
25ff0 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
26000 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
26010 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
26020 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
26030 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  ing..**.** [SQLI
26040 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
26050 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
26060 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
26070 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
26080 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
26090 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
260a0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
260b0 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
260c0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
260d0 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
260e0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
260f0 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
26100 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
26110 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
26120 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
26130 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
26140 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
26150 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
26160 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
26170 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
26180 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
26190 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
261a0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
261b0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
261c0 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
261d0 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
261e0 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
261f0 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
26200 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
26210 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
26220 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
26230 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
26240 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
26250 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
26260 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
26270 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
26280 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
26290 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
262a0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
262b0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
262c0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
262d0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
262e0 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
262f0 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
26300 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
26310 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
26320 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
26330 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c  ]..** With the l
26340 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
26350 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
26360 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
26370 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
26380 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
26390 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
263a0 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
263b0 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
263c0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
263d0 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
263e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
263f0 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
26400 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26410 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 20 69  .  In the "v2" i
26420 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
26430 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
26440 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
26450 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
26460 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
26470 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
26480 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
26490 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
264a0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
264b0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
264c0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
264d0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
264e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
264f0 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
26500 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
26510 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
26520 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
26530 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
26540 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
26550 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
26560 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
26570 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
26580 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
26590 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
265a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
265b0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
265c0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
265d0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
265e0 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
265f0 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n time..**.** <b
26600 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
26610 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
26620 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
26630 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
26640 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
26650 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
26660 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
26670 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
26680 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
26690 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
266a0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
266b0 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
266c0 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
266d0 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
266e0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
266f0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
26700 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
26710 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
26720 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
26730 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
26740 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
26750 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
26760 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
26770 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
26780 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
26790 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
267a0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
267b0 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
267c0 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
267d0 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
267e0 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
267f0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
26800 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
26810 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
26820 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
26830 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
26840 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
26850 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
26860 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
26870 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
26880 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
26890 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
268a0 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
268b0 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
268c0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
268d0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
268e0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
268f0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
26900 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
26910 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 32 30 32  S:.**.** {H13202
26920 7d 20 20 49 66 20 74 68 65 20 5b 70 72 65 70 61  }  If the [prepa
26930 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
26940 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20   is ready to be 
26950 72 75 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  run, then.**    
26960 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
26970 73 74 65 70 28 53 29 5d 20 61 64 76 61 6e 63 65  step(S)] advance
26980 73 20 74 68 61 74 20 70 72 65 70 61 72 65 64 20  s that prepared 
26990 73 74 61 74 65 6d 65 6e 74 20 75 6e 74 69 6c 0a  statement until.
269a0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 6d  **           com
269b0 70 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c  pletion or until
269c0 20 69 74 20 69 73 20 72 65 61 64 79 20 74 6f 20   it is ready to 
269d0 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72  return another r
269e0 6f 77 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ow of the.**    
269f0 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65         result se
26a00 74 2c 20 6f 72 20 75 6e 74 69 6c 20 61 6e 20 5b  t, or until an [
26a10 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
26a20 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 0a 2a  t | interrupt].*
26a30 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 61  *           or a
26a40 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
26a50 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  occurs..**.** {H
26a60 31 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20 63  15304}  When a c
26a70 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
26a80 73 74 65 70 28 53 29 5d 20 63 61 75 73 65 73 20  step(S)] causes 
26a90 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
26aa0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20  atement].**     
26ab0 20 20 20 20 20 20 53 20 74 6f 20 72 75 6e 20 74        S to run t
26ac0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 20 74 68  o completion, th
26ad0 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
26ae0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ns [SQLITE_DONE]
26af0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 36 7d  ..**.** {H15306}
26b00 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f    When a call to
26b10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
26b20 29 5d 20 73 74 6f 70 73 20 62 65 63 61 75 73 65  )] stops because
26b30 20 69 74 20 69 73 20 72 65 61 64 79 20 74 6f 0a   it is ready to.
26b40 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
26b50 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  urn another row 
26b60 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
26b70 74 2c 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53  t, it returns [S
26b80 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a  QLITE_ROW]..**.*
26b90 2a 20 7b 48 31 35 33 30 38 7d 20 20 49 66 20 61  * {H15308}  If a
26ba0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
26bb0 33 5f 73 74 65 70 28 53 29 5d 20 65 6e 63 6f 75  3_step(S)] encou
26bc0 6e 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20 20  nters an.**     
26bd0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 69        [sqlite3_i
26be0 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72  nterrupt | inter
26bf0 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74  rupt] or a run-t
26c00 69 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20  ime error,.**   
26c10 20 20 20 20 20 20 20 20 69 74 20 72 65 74 75 72          it retur
26c20 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
26c30 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 68 61  e error code tha
26c40 74 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a  t is not one of.
26c50 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51  **           [SQ
26c60 4c 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54  LITE_OK], [SQLIT
26c70 45 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c 49  E_ROW], or [SQLI
26c80 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_DONE]..**.** 
26c90 7b 48 31 35 33 31 30 7d 20 20 49 66 20 61 6e 20  {H15310}  If an 
26ca0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
26cb0 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20  pt | interrupt] 
26cc0 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  or a run-time er
26cd0 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ror.**          
26ce0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 61   occurs during a
26cf0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
26d00 33 5f 73 74 65 70 28 53 29 5d 0a 2a 2a 20 20 20  3_step(S)].**   
26d10 20 20 20 20 20 20 20 20 66 6f 72 20 61 20 5b 70          for a [p
26d20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26d30 74 5d 20 53 20 63 72 65 61 74 65 64 20 75 73 69  t] S created usi
26d40 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ng.**           
26d50 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
26d60 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
26d70 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  re()] or.**     
26d80 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
26d90 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65  repare16()], the
26da0 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72  n the function r
26db0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
26dc0 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49             [SQLI
26dd0 54 45 5f 45 52 52 4f 52 5d 2c 20 5b 53 51 4c 49  TE_ERROR], [SQLI
26de0 54 45 5f 42 55 53 59 5d 2c 20 6f 72 20 5b 53 51  TE_BUSY], or [SQ
26df0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2f  LITE_MISUSE]..*/
26e00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
26e10 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
26e20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26e30 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
26e40 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
26e50 20 73 65 74 20 7b 48 31 33 37 37 30 7d 20 3c 53   set {H13770} <S
26e60 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74  10700>.**.** Ret
26e70 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
26e80 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65  of values in the
26e90 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
26ea0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a  the result set..
26eb0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
26ec0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37 31 7d  :.**.** {H13771}
26ed0 20 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74    After a call t
26ee0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
26ef0 53 29 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73  S)] that returns
26f00 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 0a 2a   [SQLITE_ROW],.*
26f10 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20  *           the 
26f20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
26f30 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 20  unt(S)] routine 
26f40 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
26f50 73 61 6d 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20  same value.**   
26f60 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20 5b          as the [
26f70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
26f80 6f 75 6e 74 28 53 29 5d 20 66 75 6e 63 74 69 6f  ount(S)] functio
26f90 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37 32  n..**.** {H13772
26fa0 7d 20 20 41 66 74 65 72 20 5b 73 71 6c 69 74 65  }  After [sqlite
26fb0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 72  3_step(S)] has r
26fc0 65 74 75 72 6e 65 64 20 61 6e 79 20 76 61 6c 75  eturned any valu
26fd0 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20  e other than.** 
26fe0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
26ff0 45 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f 72 65  E_ROW] or before
27000 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
27010 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
27020 65 64 20 6f 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ed on the.**    
27030 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
27040 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72 20   statement] for 
27050 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
27060 69 6e 63 65 20 69 74 20 77 61 73 0a 2a 2a 20 20  ince it was.**  
27070 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
27080 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
27090 61 72 65 64 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ared] or [sqlite
270a0 33 5f 72 65 73 65 74 20 7c 20 72 65 73 65 74 5d  3_reset | reset]
270b0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  ,.**           t
270c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  he [sqlite3_data
270d0 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69  _count(S)] routi
270e0 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  ne returns zero.
270f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
27100 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
27110 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
27120 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27130 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
27140 74 61 74 79 70 65 73 20 7b 48 31 30 32 36 35 7d  tatypes {H10265}
27150 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 31 32 30   <S10110><S10120
27160 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  >.** KEYWORDS: S
27170 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
27180 20 7b 48 31 30 32 36 36 7d 20 45 76 65 72 79 20   {H10266} Every 
27190 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
271a0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
271b0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
271c0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
271d0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
271e0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
271f0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
27200 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
27210 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
27220 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
27230 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
27240 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44  LL.** </ul> {END
27250 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
27260 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
27270 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
27280 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
27290 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
272a0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
272b0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
272c0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
272d0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
272e0 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
272f0 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
27300 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
27310 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
27320 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
27330 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
27340 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
27350 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
27360 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
27370 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
27380 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
27390 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
273a0 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
273b0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
273c0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
273d0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
273e0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
273f0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
27400 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
27410 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
27420 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
27430 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
27440 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
27450 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
27460 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
27470 51 75 65 72 79 20 7b 48 31 33 38 30 30 7d 20 3c  Query {H13800} <
27480 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10700>.** KEYWO
27490 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
274a0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
274b0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
274c0 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
274d0 73 75 6c 74 20 73 65 74 20 71 75 65 72 79 22 20  sult set query" 
274e0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
274f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
27500 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
27510 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
27520 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
27530 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
27540 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
27550 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61 73 65  .  In every case
27560 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
27570 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
27580 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
27590 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
275a0 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
275b0 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
275c0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
275d0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
275e0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
275f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
27600 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
27610 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
27620 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
27630 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
27640 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
27650 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
27660 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
27670 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65  eturned.  The le
27680 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
27690 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
276a0 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
276b0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
276c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
276d0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
276e0 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
276f0 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
27700 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
27710 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
27720 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
27730 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
27740 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
27750 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
27760 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
27770 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
27780 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
27790 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
277a0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
277b0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
277c0 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
277d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
277e0 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
277f0 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
27800 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
27810 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
27820 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
27830 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27840 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
27850 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
27860 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
27870 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
27880 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
27890 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
278a0 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
278b0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
278c0 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
278d0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
278e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
278f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
27900 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
27910 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
27920 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
27930 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
27940 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
27950 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
27960 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
27970 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
27980 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
27990 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
279a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
279b0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
279c0 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
279d0 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
279e0 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
279f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
27a00 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e  umn.  The return
27a10 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
27a20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
27a30 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
27a40 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
27a50 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
27a60 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
27a70 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
27a80 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
27a90 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
27aa0 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
27ab0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
27ac0 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
27ad0 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
27ae0 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
27af0 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
27b00 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
27b10 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
27b20 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
27b30 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
27b40 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
27b50 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
27b60 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
27b70 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
27b80 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
27b90 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
27ba0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
27bb0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
27bc0 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
27bd0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
27be0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
27bf0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
27c00 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
27c10 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
27c20 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
27c30 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
27c40 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20  r string..** If 
27c50 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
27c60 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
27c70 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
27c80 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
27c90 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
27ca0 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
27cb0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
27cc0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
27cd0 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
27ce0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
27cf0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
27d00 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
27d10 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
27d20 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
27d30 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
27d40 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
27d50 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
27d60 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
27d70 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
27d80 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20   string..** The 
27d90 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64  value returned d
27da0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
27db0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
27dc0 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  tor at the end.*
27dd0 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
27de0 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74    For clarity: t
27df0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
27e00 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
27e10 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
27e20 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
27e30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
27e40 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53  racters..**.** S
27e50 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
27e60 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
27e70 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
27e80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
27e90 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
27ea0 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
27eb0 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72   always zero ter
27ec0 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65  minated.  The re
27ed0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
27ee0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
27ef0 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
27f00 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
27f10 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a  is an arbitrary.
27f20 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73  ** pointer, poss
27f30 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c  ibly even a NULL
27f40 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
27f50 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
27f60 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75  mn_bytes16() rou
27f70 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
27f80 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
27f90 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74  n_bytes().** but
27fa0 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75   leaves the resu
27fb0 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20  lt in UTF-16 in 
27fc0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
27fd0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46  r instead of UTF
27fe0 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20  -8..** The zero 
27ff0 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f  terminator is no
28000 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  t included in th
28010 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20  is count..**.** 
28020 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
28030 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
28040 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
28050 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
28060 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28070 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
28080 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
28090 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
280a0 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
280b0 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
280c0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
280d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
280e0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
280f0 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
28100 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28110 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
28120 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
28130 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
28140 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
28150 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
28160 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
28170 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
28180 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
28190 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
281a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
281b0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
281c0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
281d0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
281e0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
281f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
28200 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
28210 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
28220 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
28230 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  iate.  For.** ex
28240 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
28250 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
28260 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
28270 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
28280 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
28290 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
282a0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
282b0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
282c0 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
282d0 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
282e0 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f  ally.  The follo
282f0 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
28300 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
28310 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
28320 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
28330 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
28340 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
28350 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
28360 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
28370 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
28380 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
28390 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
283a0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
283b0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
283c0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
283d0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
283e0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
283f0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
28400 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
28410 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
28420 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
28430 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
28440 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
28450 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
28460 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
28470 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
28480 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
28490 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
284a0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
284b0 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
284c0 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
284d0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
284e0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
284f0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
28500 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
28510 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
28520 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
28530 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
28540 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
28550 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
28560 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
28570 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
28580 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
28590 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
285a0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
285b0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
285c0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
285d0 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
285e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
285f0 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
28600 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
28610 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
28620 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
28630 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
28640 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
28650 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
28660 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
28670 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
28680 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
28690 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
286a0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
286b0 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
286c0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
286d0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
286e0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
286f0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
28700 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
28710 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
28720 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
28730 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
28740 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
28750 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
28760 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
28770 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
28780 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
28790 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
287a0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  * </blockquote>.
287b0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
287c0 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
287d0 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
287e0 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
287f0 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
28800 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
28810 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
28820 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
28830 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
28840 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
28850 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
28860 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
28870 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
28880 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
28890 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
288a0 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
288b0 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
288c0 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
288d0 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
288e0 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
288f0 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
28900 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
28910 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
28920 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
28930 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
28940 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
28950 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
28960 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
28970 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28980 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
28990 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
289a0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
289b0 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
289c0 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
289d0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
289e0 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
289f0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
28a00 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
28a10 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
28a20 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
28a30 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
28a40 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
28a50 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
28a60 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
28a70 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
28a80 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
28a90 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
28aa0 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
28ab0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
28ac0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
28ad0 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
28ae0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
28af0 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
28b00 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
28b10 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
28b20 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
28b30 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
28b40 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
28b50 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
28b60 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
28b70 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
28b80 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
28b90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
28ba0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
28bb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
28bc0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
28bd0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
28be0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
28bf0 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
28c00 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
28c10 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  ** Conversions b
28c20 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
28c30 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
28c40 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
28c50 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
28c60 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
28c70 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
28c80 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
28c90 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
28ca0 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
28cb0 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
28cc0 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77  nter points to w
28cd0 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
28ce0 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
28cf0 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
28d00 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
28d10 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
28d20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
28d30 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
28d40 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
28d50 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
28d60 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
28d70 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
28d80 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
28d90 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
28da0 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
28db0 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
28dc0 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
28dd0 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
28de0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
28df0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
28e00 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
28e10 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
28e20 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
28e30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
28e40 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
28e50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
28e60 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
28e70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28e80 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
28e90 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
28ea0 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
28eb0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
28ec0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
28ed0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
28ee0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
28ef0 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
28f00 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
28f10 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
28f20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
28f30 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
28f40 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
28f50 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
28f60 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
28f70 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
28f80 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
28f90 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
28fa0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
28fb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28fc0 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
28fd0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
28fe0 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
28ff0 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
29000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29010 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
29020 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
29030 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
29040 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29050 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
29060 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
29070 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
29080 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
29090 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
290a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
290b0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  )..**.** The poi
290c0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
290d0 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
290e0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
290f0 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
29100 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
29110 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
29120 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
29130 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
29140 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
29150 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
29160 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  ed.  The memory 
29170 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
29180 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
29190 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
291a0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
291b0 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
291c0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
291d0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
291e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
291f0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
29200 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
29210 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
29220 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
29230 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20  .** If a memory 
29240 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
29250 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
29260 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
29270 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
29280 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
29290 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
292a0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
292b0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
292c0 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
292d0 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
292e0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
292f0 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
29300 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
29310 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
29320 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
29330 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
29340 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
29350 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  M]..**.** INVARI
29360 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
29370 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  803} The [sqlite
29380 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c  3_column_blob(S,
29390 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
293a0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
293b0 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
293c0 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
293d0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
293e0 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
293f0 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70         the [prep
29400 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29410 53 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e  S into a BLOB an
29420 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61  d then returns a
29430 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
29440 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76  nter to the conv
29450 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a  erted value..**.
29460 2a 2a 20 7b 48 31 33 38 30 36 7d 20 54 68 65 20  ** {H13806} The 
29470 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29480 62 79 74 65 73 28 53 2c 4e 29 5d 20 69 6e 74 65  bytes(S,N)] inte
29490 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
294a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
294b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
294c0 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
294d0 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
294e0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
294f0 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
29500 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
29510 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
29520 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
29530 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
29540 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
29550 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53  e3_column_blob(S
29560 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  ,N)] or.**      
29570 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
29580 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 2e 0a  umn_text(S,N)]..
29590 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 39 7d 20 54  **.** {H13809} T
295a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
295b0 6d 6e 5f 62 79 74 65 73 31 36 28 53 2c 4e 29 5d  mn_bytes16(S,N)]
295c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
295d0 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
295e0 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
295f0 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
29600 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74   (exclusive of t
29610 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  he.**          z
29620 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f  ero terminator o
29630 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68  n the string) th
29640 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
29650 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
29660 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63     most recent c
29670 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
29680 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c  column_text16(S,
29690 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  N)]..**.** {H138
296a0 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
296b0 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 53  _column_double(S
296c0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
296d0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
296e0 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
296f0 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
29700 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
29710 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a  ult set for the.
29720 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
29730 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29740 20 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69   S into a floati
29750 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61  ng point value a
29760 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
29770 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
29780 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a   that value..**.
29790 2a 2a 20 7b 48 31 33 38 31 35 7d 20 54 68 65 20  ** {H13815} The 
297a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
297b0 69 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  int(S,N)] interf
297c0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
297d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
297e0 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
297f0 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
29800 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
29810 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
29820 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29830 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36  ment] S into a 6
29840 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
29850 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20  eger and.**     
29860 20 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65       returns the
29870 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f   lower 32 bits o
29880 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a  f that integer..
29890 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 38 7d 20 54  **.** {H13818} T
298a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
298b0 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20 69  mn_int64(S,N)] i
298c0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
298d0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
298e0 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
298f0 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
29900 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
29910 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  t for the.**    
29920 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
29930 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
29940 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65  o a 64-bit signe
29950 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a  d integer and.**
29960 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
29970 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74  s a copy of that
29980 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
29990 7b 48 31 33 38 32 31 7d 20 54 68 65 20 5b 73 71  {H13821} The [sq
299a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
299b0 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  t(S,N)] interfac
299c0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
299d0 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
299e0 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
299f0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
29a00 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
29a10 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
29a20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29a30 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72  nt] S into a zer
29a40 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
29a50 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  -8.**          s
29a60 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
29a70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
29a80 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  hat string..**.*
29a90 2a 20 7b 48 31 33 38 32 34 7d 20 54 68 65 20 5b  * {H13824} The [
29aa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29ab0 65 78 74 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65  ext16(S,N)] inte
29ac0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
29ad0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
29ae0 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
29af0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
29b00 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
29b10 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
29b20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
29b30 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
29b40 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
29b50 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20   2-byte.**      
29b60 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d      aligned UTF-
29b70 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
29b80 72 64 65 72 20 73 74 72 69 6e 67 20 61 6e 64 20  rder string and 
29b90 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
29ba0 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f      a pointer to
29bb0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
29bc0 0a 2a 2a 20 7b 48 31 33 38 32 37 7d 20 54 68 65  .** {H13827} The
29bd0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29be0 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _type(S,N)] inte
29bf0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
29c00 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66            one of
29c10 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20   [SQLITE_NULL], 
29c20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
29c30 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  , [SQLITE_FLOAT]
29c40 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  ,.**          [S
29c50 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20  QLITE_TEXT], or 
29c60 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73  [SQLITE_BLOB] as
29c70 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
29c80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
29c90 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
29ca0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
29cb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
29cc0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
29cd0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
29ce0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
29cf0 2a 2a 20 7b 48 31 33 38 33 30 7d 20 54 68 65 20  ** {H13830} The 
29d00 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29d10 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e 74 65  value(S,N)] inte
29d20 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 0a  rface returns a.
29d30 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e  **          poin
29d40 74 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70 72 6f  ter to an [unpro
29d50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
29d60 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
29d70 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
29d80 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
29d90 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
29da0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
29db0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
29dc0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
29dd0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
29de0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
29df0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
29e00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29e10 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
29e20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
29e30 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
29e40 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
29e50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29e60 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
29e70 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
29e80 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
29e90 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
29ea0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29eb0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
29ec0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
29ed0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29ee0 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
29ef0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
29f00 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
29f10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
29f20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  iCol);.const uns
29f30 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
29f40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
29f50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29f60 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
29f70 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
29f80 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
29f90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
29fa0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
29fb0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
29fc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29fd0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
29fe0 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
29ff0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
2a000 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2a010 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
2a020 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
2a030 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2a040 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33  ent Object {H133
2a050 30 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33 30  00} <S70300><S30
2a060 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  100>.**.** The s
2a070 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2a080 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
2a090 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
2a0a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a0b0 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ment]..** If the
2a0c0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65   statement was e
2a0d0 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66  xecuted successf
2a0e0 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63  ully or not exec
2a0f0 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65  uted at all, the
2a100 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69  n.** SQLITE_OK i
2a110 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20 65  s returned. If e
2a120 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
2a130 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64  statement failed
2a140 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72   then an.** [err
2a150 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  or code] or [ext
2a160 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
2a170 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
2a180 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
2a190 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
2a1a0 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
2a1b0 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
2a1c0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  n of the.** [pre
2a1d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a1e0 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61  .  If the virtua
2a1f0 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f  l machine has no
2a200 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  t.** completed e
2a210 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68  xecution when th
2a220 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  is routine is ca
2a230 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69  lled, that is li
2a240 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69  ke.** encounteri
2a250 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61  ng an error or a
2a260 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  n [sqlite3_inter
2a270 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74  rupt | interrupt
2a280 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65  ]..** Incomplete
2a290 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20   updates may be 
2a2a0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20  rolled back and 
2a2b0 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e  transactions can
2a2c0 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64  celed,.** depend
2a2d0 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75  ing on the circu
2a2e0 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68  mstances, and th
2a2f0 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  e.** [error code
2a300 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20  ] returned will 
2a310 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  be [SQLITE_ABORT
2a320 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
2a330 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  NTS:.**.** {H113
2a340 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  02} The [sqlite3
2a350 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e  _finalize(S)] in
2a360 74 65 72 66 61 63 65 20 64 65 73 74 72 6f 79 73  terface destroys
2a370 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2a380 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a390 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c 65  ment] S and rele
2a3a0 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  ases all.**     
2a3b0 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20       memory and 
2a3c0 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20 68  file resources h
2a3d0 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a 65  eld by that obje
2a3e0 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30  ct..**.** {H1130
2a3f0 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  4} If the most r
2a400 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2a410 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2a420 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
2a430 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
2a440 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
2a450 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a  ned an error,.**
2a460 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
2a470 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a480 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68 61  (S)] returns tha
2a490 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f  t same error..*/
2a4a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e  .int sqlite3_fin
2a4b0 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
2a4c0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2a4d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2a4e0 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
2a4f0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
2a500 48 31 33 33 33 30 7d 20 3c 53 37 30 33 30 30 3e  H13330} <S70300>
2a510 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2a520 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
2a530 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
2a540 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
2a550 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2a560 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
2a570 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
2a580 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
2a590 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41  e-executed..** A
2a5a0 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
2a5b0 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
2a5c0 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
2a5d0 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
2a5e0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
2a5f0 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
2a600 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
2a610 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
2a620 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
2a630 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2a640 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
2a650 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
2a660 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20 54 68  *.** {H11332} Th
2a670 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2a680 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
2a690 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
2a6a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2a6b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61 63  .**          bac
2a6c0 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
2a6d0 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
2a6e0 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34  m..**.** {H11334
2a6f0 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
2a700 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2a710 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2a720 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2a730 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2a740 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
2a750 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2a760 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2a770 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
2a780 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
2a790 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
2a7a0 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
2a7b0 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20  ed on S,.**     
2a7c0 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74       then [sqlit
2a7d0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
2a7e0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
2a7f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d  ..**.** {H11336}
2a800 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   If the most rec
2a810 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2a820 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
2a830 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2a840 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2a850 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74  ement] S indicat
2a860 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65  ed an error, the
2a870 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  n.**          [s
2a880 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2a890 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
2a8a0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2a8b0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  ode]..**.** {H11
2a8c0 33 33 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  338} The [sqlite
2a8d0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2a8e0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
2a8f0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
2a900 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
2a910 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
2a920 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
2a930 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
2a940 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
2a950 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
2a960 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
2a970 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2a980 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
2a990 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
2a9a0 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31  QL Functions {H1
2a9b0 36 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6100} <S20200>.*
2a9c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
2a9d0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
2a9e0 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
2a9f0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
2aa00 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2aa10 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
2aa20 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
2aa30 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2aa40 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
2aa50 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69  These two functi
2aa60 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
2aa70 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
2aa80 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2aa90 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
2aaa0 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
2aab0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
2aac0 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
2aad0 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
2aae0 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
2aaf0 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
2ab00 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
2ab10 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
2ab20 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68 65  ence between the
2ab30 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20  .** two is that 
2ab40 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
2ab50 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f  eter, the name o
2ab60 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 20 66  f the (scalar) f
2ab70 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2ab80 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f  gregate, is enco
2ab90 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72  ded in UTF-8 for
2aba0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2abb0 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55  function() and U
2abc0 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c  TF-16.** for sql
2abd0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2abe0 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20  tion16()..**.** 
2abf0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2ac00 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
2ac10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2ac20 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
2ac30 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
2ac40 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49   to be added.  I
2ac50 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  f a single progr
2ac60 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  am uses more tha
2ac70 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
2ac80 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74  * connection int
2ac90 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51  ernally, then SQ
2aca0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74  L functions must
2acb0 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76 69   be added indivi
2acc0 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63  dually to.** eac
2acd0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
2ace0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ction..**.** The
2acf0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2ad00 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
2ad10 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2ad20 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
2ad30 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
2ad40 20 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20    The length of 
2ad50 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
2ad60 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
2ad70 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a  , exclusive of.*
2ad80 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  * the zero-termi
2ad90 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61  nator.  Note tha
2ada0 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74  t the name lengt
2adb0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79  h limit is in by
2adc0 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72  tes, not.** char
2add0 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74  acters.  Any att
2ade0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
2adf0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
2ae00 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
2ae10 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
2ae20 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65  SQLITE_ERROR] be
2ae30 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
2ae40 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61  .** The third pa
2ae50 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
2ae60 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2ae70 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
2ae80 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2ae90 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
2aea0 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
2aeb0 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
2aec0 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
2aed0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2aee0 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
2aef0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
2af00 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
2af10 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2af20 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
2af30 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b  cifies what.** [
2af40 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
2af50 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
2af60 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
2af70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
2af80 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41  s parameters.  A
2af90 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ny SQL function 
2afa0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
2afb0 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f  hould be able to
2afc0 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69   work.** work wi
2afd0 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  th UTF-8, UTF-16
2afe0 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e  le, or UTF-16be.
2aff0 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65    But some imple
2b000 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  mentations may b
2b010 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69  e.** more effici
2b020 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63  ent with one enc
2b030 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68  oding than anoth
2b040 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f 77  er.  It is allow
2b050 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
2b060 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2b070 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
2b080 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b090 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
2b0a0 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
2b0b0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2b0c0 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
2b0d0 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
2b0e0 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e  TextRep..** When
2b0f0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2b100 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2b110 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
2b120 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
2b130 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
2b140 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
2b150 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
2b160 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
2b170 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
2b180 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
2b190 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
2b1a0 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
2b1b0 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
2b1c0 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69  t text.** encodi
2b1d0 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
2b1e0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
2b1f0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b  ment should be [
2b200 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
2b210 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72  ** The fifth par
2b220 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
2b230 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
2b240 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
2b250 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
2b260 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
2b270 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
2b280 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
2b290 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2b2a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  )]..**.** The se
2b2b0 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e  venth, eighth an
2b2c0 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  d ninth paramete
2b2d0 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
2b2e0 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
2b2f0 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
2b300 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
2b310 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
2b320 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2b330 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2b340 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53  gate. A scalar S
2b350 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
2b360 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
2b370 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
2b380 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
2b390 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74  only, NULL point
2b3a0 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ers should be pa
2b3b0 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
2b3c0 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
2b3d0 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61  parameters. An a
2b3e0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2b3f0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
2b400 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2b410 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
2b420 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
2b430 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
2b440 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20  d for xFunc. To 
2b450 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
2b460 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
2b470 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
2b480 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61   pass NULL for a
2b490 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
2b4a0 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  n callbacks..**.
2b4b0 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74  ** It is permitt
2b4c0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
2b4d0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2b4e0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2b4f0 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
2b500 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
2b510 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
2b520 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
2b530 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
2b540 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
2b550 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
2b560 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51  t encodings.  SQ
2b570 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
2b580 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2b590 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  ion most closely
2b5a0 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
2b5b0 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
2b5c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2b5d0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   used..**.** INV
2b5e0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2b5f0 48 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c  H16103} The [sql
2b600 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b610 74 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65 72 66  tion16()] interf
2b620 61 63 65 20 62 65 68 61 76 65 73 20 65 78 61 63  ace behaves exac
2b630 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tly.**          
2b640 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 63 72  like [sqlite3_cr
2b650 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2b660 20 69 6e 20 65 76 65 72 79 20 77 61 79 20 65 78   in every way ex
2b670 63 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20  cept that it.** 
2b680 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 70 72           interpr
2b690 65 74 73 20 74 68 65 20 7a 46 75 6e 63 74 69 6f  ets the zFunctio
2b6a0 6e 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 61  nName argument a
2b6b0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2b6c0 64 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20  d UTF-16.**     
2b6d0 20 20 20 20 20 6e 61 74 69 76 65 20 62 79 74 65       native byte
2b6e0 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f   order instead o
2b6f0 66 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  f as zero-termin
2b700 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  ated UTF-8..**.*
2b710 2a 20 7b 48 31 36 31 30 36 7d 20 41 20 73 75 63  * {H16106} A suc
2b720 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
2b730 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  on of.**        
2b740 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    the [sqlite3_c
2b750 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2b760 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74  ,X,N,E,...)] int
2b770 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
2b780 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
2b790 72 65 70 6c 61 63 65 73 20 63 61 6c 6c 62 61 63  replaces callbac
2b7a0 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74  k functions in t
2b7b0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2b7c0 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20  nection] D.**   
2b7d0 20 20 20 20 20 20 20 75 73 65 64 20 74 6f 20 69         used to i
2b7e0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
2b7f0 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20   function named 
2b800 58 20 77 69 74 68 20 4e 20 70 61 72 61 6d 65 74  X with N paramet
2b810 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
2b820 61 6e 64 20 68 61 76 69 6e 67 20 61 20 70 72 65  and having a pre
2b830 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
2b840 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a  ding of E..**.**
2b850 20 7b 48 31 36 31 30 39 7d 20 41 20 73 75 63 63   {H16109} A succ
2b860 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
2b870 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2b880 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
2b890 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20  P,F,S,L)].**    
2b8a0 20 20 20 20 20 20 72 65 70 6c 61 63 65 73 20 74        replaces t
2b8b0 68 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20  he P, F, S, and 
2b8c0 4c 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e  L values from an
2b8d0 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69  y prior calls wi
2b8e0 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
2b8f0 68 65 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c  he same D, X, N,
2b900 20 61 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a   and E values..*
2b910 2a 0a 2a 2a 20 7b 48 31 36 31 31 32 7d 20 54 68  *.** {H16112} Th
2b920 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2b930 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e  e_function(D,X,.
2b940 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66  ..)] interface f
2b950 61 69 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20  ails with.**    
2b960 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 63        a return c
2b970 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45  ode of [SQLITE_E
2b980 52 52 4f 52 5d 20 69 66 20 74 68 65 20 53 51 4c  RROR] if the SQL
2b990 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58   function name X
2b9a0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2b9b0 6c 6f 6e 67 65 72 20 74 68 61 6e 20 32 35 35 20  longer than 255 
2b9c0 62 79 74 65 73 20 65 78 63 6c 75 73 69 76 65 20  bytes exclusive 
2b9d0 6f 66 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  of the zero term
2b9e0 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  inator..**.** {H
2b9f0 31 36 31 31 38 7d 20 45 69 74 68 65 72 20 46 20  16118} Either F 
2ba00 6d 75 73 74 20 62 65 20 4e 55 4c 4c 20 61 6e 64  must be NULL and
2ba10 20 53 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e   S and L are non
2ba20 2d 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 46 0a  -NULL or else F.
2ba30 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e  **          is n
2ba40 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e  on-NULL and S an
2ba50 64 20 4c 20 61 72 65 20 4e 55 4c 4c 2c 20 6f 74  d L are NULL, ot
2ba60 68 65 72 77 69 73 65 0a 2a 2a 20 20 20 20 20 20  herwise.**      
2ba70 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65      [sqlite3_cre
2ba80 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2ba90 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 72  ,N,E,P,F,S,L)] r
2baa0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45  eturns [SQLITE_E
2bab0 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  RROR]..**.** {H1
2bac0 36 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  6121} The [sqlit
2bad0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2bae0 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  on(D,...)] inter
2baf0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
2bb00 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  an.**          e
2bb10 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
2bb20 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20 74 68  LITE_BUSY] if th
2bb30 65 72 65 20 65 78 69 73 74 20 5b 70 72 65 70 61  ere exist [prepa
2bb40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a  red statements].
2bb50 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 6f  **          asso
2bb60 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2bb70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bb80 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
2bb90 48 31 36 31 32 34 7d 20 54 68 65 20 5b 73 71 6c  H16124} The [sql
2bba0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2bbb0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
2bbc0 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
2bbd0 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20   with an.**     
2bbe0 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20       error code 
2bbf0 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  of [SQLITE_ERROR
2bc00 5d 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 4e  ] if parameter N
2bc10 20 28 73 70 65 63 69 66 79 69 6e 67 20 74 68 65   (specifying the
2bc20 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20   number.**      
2bc30 20 20 20 20 6f 66 20 61 72 67 75 6d 65 6e 74 73      of arguments
2bc40 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
2bc50 74 69 6f 6e 20 62 65 69 6e 67 20 72 65 67 69 73  tion being regis
2bc60 74 65 72 65 64 29 20 69 73 20 6c 65 73 73 0a 2a  tered) is less.*
2bc70 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20  *          than 
2bc80 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
2bc90 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 48  an 127..**.** {H
2bca0 31 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69 73  16127} When N is
2bcb0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
2bcc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2bcd0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2bce0 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  N,...)].**      
2bcf0 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61      interface ca
2bd00 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74  uses callbacks t
2bd10 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72  o be invoked for
2bd20 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2bd30 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61  n.**          na
2bd40 6d 65 64 20 58 20 77 68 65 6e 20 74 68 65 20 6e  med X when the n
2bd50 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2bd60 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  ts to the SQL fu
2bd70 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  nction is.**    
2bd80 20 20 20 20 20 20 65 78 61 63 74 6c 79 20 4e 2e        exactly N.
2bd90 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 30 7d 20  .**.** {H16130} 
2bda0 57 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68  When N is -1, th
2bdb0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2bdc0 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2bdd0 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2bde0 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75     interface cau
2bdf0 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f  ses callbacks to
2be00 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   be invoked for 
2be10 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2be20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d  .**          nam
2be30 65 64 20 58 20 77 69 74 68 20 61 6e 79 20 6e 75  ed X with any nu
2be40 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2be50 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 33  s..**.** {H16133
2be60 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  } When calls to 
2be70 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2be80 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e  function(D,X,N,.
2be90 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
2bea0 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c   specify multipl
2beb0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2bec0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2bed0 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20  nction X.**     
2bee0 20 20 20 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e       and when on
2bef0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2bf00 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68   has N>=0 and th
2bf10 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d 28 2d  e other has N=(-
2bf20 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  1).**          t
2bf30 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2bf40 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  n with a non-zer
2bf50 6f 20 4e 20 69 73 20 70 72 65 66 65 72 72 65 64  o N is preferred
2bf60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 36 7d  ..**.** {H16136}
2bf70 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b   When calls to [
2bf80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2bf90 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
2bfa0 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
2bfb0 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70    specify multip
2bfc0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2bfd0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
2bfe0 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 0a 2a  unction X with.*
2bff0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
2c000 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  ame number of ar
2c010 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 20 77 69  guments N but wi
2c020 74 68 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20  th different.** 
2c030 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 69 6e           encodin
2c040 67 73 20 45 2c 20 74 68 65 6e 20 74 68 65 20 69  gs E, then the i
2c050 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
2c060 65 72 65 20 45 20 6d 61 74 63 68 65 73 20 74 68  ere E matches th
2c070 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61  e.**          da
2c080 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
2c090 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a  is preferred..**
2c0a0 0a 2a 2a 20 7b 48 31 36 31 33 39 7d 20 46 6f 72  .** {H16139} For
2c0b0 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 53 51   an aggregate SQ
2c0c0 4c 20 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74  L function creat
2c0d0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
2c0e0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72       [sqlite3_cr
2c0f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2c100 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20  X,N,E,P,0,S,L)] 
2c110 74 68 65 20 66 69 6e 61 6c 69 7a 65 72 0a 2a 2a  the finalizer.**
2c120 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
2c130 6f 6e 20 4c 20 77 69 6c 6c 20 61 6c 77 61 79 73  on L will always
2c140 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 78 61 63   be invoked exac
2c150 74 6c 79 20 6f 6e 63 65 20 69 66 20 74 68 65 0a  tly once if the.
2c160 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 65 70  **          step
2c170 20 66 75 6e 63 74 69 6f 6e 20 53 20 69 73 20 63   function S is c
2c180 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
2c190 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  e times..**.** {
2c1a0 48 31 36 31 34 32 7d 20 57 68 65 6e 20 53 51 4c  H16142} When SQL
2c1b0 69 74 65 20 69 6e 76 6f 6b 65 73 20 65 69 74 68  ite invokes eith
2c1c0 65 72 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  er the xFunc or 
2c1d0 78 53 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f  xStep function o
2c1e0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  f.**          an
2c1f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2c200 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2c210 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 20 63  n or aggregate c
2c220 72 65 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  reated.**       
2c230 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63     by [sqlite3_c
2c240 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2c250 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72  ] or [sqlite3_cr
2c260 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2c270 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
2c280 74 68 65 6e 20 74 68 65 20 61 72 72 61 79 20 6f  then the array o
2c290 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
2c2a0 5d 20 6f 62 6a 65 63 74 73 20 70 61 73 73 65 64  ] objects passed
2c2b0 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   as the.**      
2c2c0 20 20 20 20 74 68 69 72 64 20 70 61 72 61 6d 65      third parame
2c2d0 74 65 72 20 61 72 65 20 61 6c 77 61 79 73 20 5b  ter are always [
2c2e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c2f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2c300 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2c310 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c320 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2c330 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2c340 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2c350 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2c360 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2c370 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2c380 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2c390 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2c3a0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2c3b0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2c3c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2c3d0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2c3e0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2c3f0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2c400 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
2c410 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2c420 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
2c430 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
2c440 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
2c450 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
2c460 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
2c470 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
2c480 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
2c490 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2c4a0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2c4b0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2c4c0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
2c4d0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2c4e0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2c4f0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
2c500 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c510 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
2c520 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
2c530 69 6e 67 73 20 7b 48 31 30 32 36 37 7d 20 3c 53  ings {H10267} <S
2c540 35 30 32 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a  50200> <H16100>.
2c550 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2c560 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
2c570 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
2c580 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
2c590 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
2c5a0 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
2c5b0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
2c5c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2c5d0 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
2c5e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2c5f0 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
2c600 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2c610 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
2c620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2c630 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
2c640 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
2c650 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
2c660 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
2c670 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
2c680 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
2c690 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
2c6a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2c6b0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
2c6c0 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
2c6d0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2c6e0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
2c6f0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 73 6f  * CAPI3REF: Obso
2c700 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  lete Functions.*
2c710 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2c720 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77  ions are all now
2c730 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f   obsolete.  In o
2c740 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
2c750 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
2c760 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
2c770 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77 65 20   older code, we 
2c780 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75 70 70  continue to supp
2c790 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e  ort.** these fun
2c7a0 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72  ctions.  However
2c7b0 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e  , new developmen
2c7c0 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c  t projects shoul
2c7d0 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
2c7e0 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
2c7f0 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
2c800 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
2c810 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
2c820 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
2c830 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
2c840 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
2c850 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a   want they do..*
2c860 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  /.int sqlite3_ag
2c870 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
2c880 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2c890 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70  .int sqlite3_exp
2c8a0 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
2c8b0 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
2c8c0 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
2c8d0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2c8e0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
2c8f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  ;.int sqlite3_gl
2c900 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
2c910 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  d);.void sqlite3
2c920 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
2c930 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
2c940 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
2c950 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
2c960 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
2c970 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  ,void*,sqlite3_i
2c980 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
2c990 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
2c9a0 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
2c9b0 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20  arameter Values 
2c9c0 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32 30 30  {H15100} <S20200
2c9d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  >.**.** The C-la
2c9e0 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
2c9f0 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
2ca00 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
2ca10 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
2ca20 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
2ca30 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
2ca40 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
2ca50 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
2ca60 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
2ca70 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
2ca80 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
2ca90 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
2caa0 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
2cab0 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
2cac0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
2cad0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2cae0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
2caf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2cb00 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
2cb10 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
2cb20 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
2cb30 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2cb40 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
2cb50 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72  ..** The 4th par
2cb60 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
2cb70 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
2cb80 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
2cb90 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
2cba0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2cbb0 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
2cbc0 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
2cbd0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2cbe0 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
2cbf0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
2cc00 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
2cc10 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
2cc20 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
2cc30 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
2cc40 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2cc50 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
2cc60 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2cc70 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
2cc80 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2cc90 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2cca0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
2ccb0 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
2ccc0 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
2ccd0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2cce0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
2ccf0 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
2cd00 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
2cd10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2cd20 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
2cd30 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
2cd40 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
2cd50 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2cd60 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
2cd70 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73    these routines
2cd80 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
2cd90 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2cda0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
2cdb0 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
2cdc0 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
2cdd0 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
2cde0 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
2cdf0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
2ce00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2ce10 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
2ce20 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
2ce30 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
2ce40 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
2ce50 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
2ce60 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
2ce70 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  e.  The.** sqlit
2ce80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
2ce90 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
2cea0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
2ceb0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
2cec0 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74  xtract UTF-16 st
2ced0 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
2cee0 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
2cef0 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
2cf00 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
2cf10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
2cf20 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
2cf30 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
2cf40 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
2cf50 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
2cf60 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
2cf70 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
2cf80 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
2cf90 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
2cfa0 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
2cfb0 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
2cfc0 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
2cfd0 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
2cfe0 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
2cff0 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
2d000 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
2d010 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
2d020 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
2d030 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
2d040 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
2d050 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
2d060 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
2d070 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
2d080 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
2d090 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
2d0a0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
2d0b0 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
2d0c0 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
2d0d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  ned..**.** Pleas
2d0e0 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
2d0f0 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
2d100 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
2d110 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64  pointer returned
2d120 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
2d130 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
2d140 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d150 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
2d160 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2d170 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
2d180 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
2d190 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
2d1a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
2d1b0 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
2d1c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2d1d0 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
2d1e0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2d1f0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
2d200 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
2d210 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2d220 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
2d230 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
2d240 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
2d250 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2d260 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
2d270 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2d280 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
2d290 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2d2a0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 33  S:.**.** {H15103
2d2b0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2d2c0 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69 6e  alue_blob(V)] in
2d2d0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2d2e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2d2f0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2d300 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2d310 74 20 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20  t V into a BLOB 
2d320 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  and then.**     
2d330 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 70       returns a p
2d340 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
2d350 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a  nverted value..*
2d360 2a 0a 2a 2a 20 7b 48 31 35 31 30 36 7d 20 54 68  *.** {H15106} Th
2d370 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2d380 5f 62 79 74 65 73 28 56 29 5d 20 69 6e 74 65 72  _bytes(V)] inter
2d390 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2d3a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
2d3b0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2d3c0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
2d3d0 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66  ng (exclusive of
2d3e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2d3f0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2d400 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20   on the string) 
2d410 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2d420 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
2d430 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74       most recent
2d440 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2d450 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d  3_value_blob(V)]
2d460 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2d470 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2d480 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ext(V)]..**.** {
2d490 48 31 35 31 30 39 7d 20 54 68 65 20 5b 73 71 6c  H15109} The [sql
2d4a0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2d4b0 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  16(V)] interface
2d4c0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2d4d0 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
2d4e0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2d4f0 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
2d500 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
2d510 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
2d520 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
2d530 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
2d540 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
2d550 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
2d560 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2d570 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2d580 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  16(V)],.**      
2d590 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c      [sqlite3_val
2d5a0 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d 2c  ue_text16be(V)],
2d5b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
2d5c0 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 2e  ue_text16le(V)].
2d5d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 32 7d 20  .**.** {H15112} 
2d5e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2d5f0 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69 6e  ue_double(V)] in
2d600 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2d610 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2d620 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2d630 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2d640 74 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74  t V into a float
2d650 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
2d660 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
2d670 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2d680 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a  f that value..**
2d690 0a 2a 2a 20 7b 48 31 35 31 31 35 7d 20 54 68 65  .** {H15115} The
2d6a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d6b0 69 6e 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63  int(V)] interfac
2d6c0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2d6d0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2d6e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2d6f0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2d700 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
2d710 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
2d720 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2d730 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20  ns the lower 32 
2d740 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74  bits of that int
2d750 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  eger..**.** {H15
2d760 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  118} The [sqlite
2d770 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 56 29  3_value_int64(V)
2d780 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2d790 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2d7a0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2d7b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d7c0 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36  bject V into a 6
2d7d0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2d7e0 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20  eger and.**     
2d7f0 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63       returns a c
2d800 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65  opy of that inte
2d810 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  ger..**.** {H151
2d820 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  21} The [sqlite3
2d830 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 20  _value_text(V)] 
2d840 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2d850 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2d860 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2d870 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2d880 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72  ect V into a zer
2d890 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2d8a0 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  -8.**          s
2d8b0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2d8c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2d8d0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  hat string..**.*
2d8e0 2a 20 7b 48 31 35 31 32 34 7d 20 54 68 65 20 5b  * {H15124} The [
2d8f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2d900 78 74 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61  xt16(V)] interfa
2d910 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2d920 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
2d930 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d940 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
2d950 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
2d960 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20  nated 2-byte.** 
2d970 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64           aligned
2d980 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
2d990 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20  yte order.**    
2d9a0 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
2d9b0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2d9c0 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
2d9d0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 37  g..**.** {H15127
2d9e0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2d9f0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29  alue_text16be(V)
2da00 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2da10 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2da20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2da30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2da40 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a  bject V into a z
2da50 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32  ero-terminated 2
2da60 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  -byte.**        
2da70 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36    aligned UTF-16
2da80 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20   big-endian.**  
2da90 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
2daa0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2dab0 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
2dac0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  ing..**.** {H151
2dad0 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  30} The [sqlite3
2dae0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2daf0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2db00 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2db10 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
2db20 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2db30 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
2db40 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2db50 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20   2-byte.**      
2db60 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d      aligned UTF-
2db70 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  16 little-endian
2db80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
2db90 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ing and returns 
2dba0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
2dbb0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
2dbc0 7b 48 31 35 31 33 33 7d 20 54 68 65 20 5b 73 71  {H15133} The [sq
2dbd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
2dbe0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (V)] interface r
2dbf0 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
2dc00 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54     one of [SQLIT
2dc10 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_NULL], [SQLITE
2dc20 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49  _INTEGER], [SQLI
2dc30 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20  TE_FLOAT],.**   
2dc40 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
2dc50 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  EXT], or [SQLITE
2dc60 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70  _BLOB] as approp
2dc70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20  riate for.**    
2dc80 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
2dc90 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2dca0 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33   V..**.** {H1513
2dcb0 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
2dcc0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
2dcd0 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  pe(V)] interface
2dce0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20   converts.**    
2dcf0 20 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74 65        the [prote
2dd00 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2dd10 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2dd20 6f 20 65 69 74 68 65 72 20 61 6e 20 69 6e 74 65  o either an inte
2dd30 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ger or.**       
2dd40 20 20 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f     a floating po
2dd50 69 6e 74 20 76 61 6c 75 65 20 69 66 20 69 74 20  int value if it 
2dd60 63 61 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f 75  can do so withou
2dd70 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20  t loss of.**    
2dd80 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f        informatio
2dd90 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 6f  n, and returns o
2dda0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55  ne of [SQLITE_NU
2ddb0 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  LL],.**         
2ddc0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2ddd0 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ], [SQLITE_FLOAT
2dde0 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
2ddf0 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
2de00 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61   [SQLITE_BLOB] a
2de10 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
2de20 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2de30 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2de40 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2de50 63 74 20 56 20 61 66 74 65 72 20 74 68 65 20 63  ct V after the c
2de60 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74 65 6d 70  onversion attemp
2de70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  t..*/.const void
2de80 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2de90 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c  blob(sqlite3_val
2dea0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2deb0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
2dec0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2ded0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2dee0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
2def0 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65  _value*);.double
2df00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
2df10 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
2df20 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2df30 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c  e3_value_int(sql
2df40 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71  ite3_value*);.sq
2df50 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
2df60 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
2df70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2df80 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
2df90 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61  char *sqlite3_va
2dfa0 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
2dfb0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2dfc0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2dfd0 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74  lue_text16(sqlit
2dfe0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
2dff0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2e000 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
2e010 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2e020 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2e030 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2e040 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  be(sqlite3_value
2e050 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2e060 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
2e070 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2e080 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
2e090 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
2e0a0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
2e0b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
2e0c0 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
2e0d0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b  nction Context {
2e0e0 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30 3e  H16210} <S20200>
2e0f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65  .**.** The imple
2e100 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67  mentation of agg
2e110 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2e120 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f  ions use this ro
2e130 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
2e140 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65  e.** a structure
2e150 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
2e160 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
2e170 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
2e180 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
2e190 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72  gate_context() r
2e1a0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
2e1b0 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69 63   for a.** partic
2e1c0 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c 20  ular aggregate, 
2e1d0 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73  SQLite allocates
2e1e0 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72   nBytes of memor
2e1f0 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68  y, zeroes out th
2e200 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e  at.** memory, an
2e210 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
2e220 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65  ter to it. On se
2e230 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
2e240 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
2e250 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2e260 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
2e270 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
2e280 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65  te function inde
2e290 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62  x,.** the same b
2e2a0 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
2e2b0 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  d. The implement
2e2c0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67 67  ation of the agg
2e2d0 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a 2a  regate can use.*
2e2e0 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 62  * the returned b
2e2f0 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c  uffer to accumul
2e300 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20  ate data..**.** 
2e310 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
2e320 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 61  ally frees the a
2e330 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 20  llocated buffer 
2e340 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
2e350 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63  te.** query conc
2e360 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
2e370 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2e380 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70   should be a cop
2e390 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
2e3a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
2e3b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
2e3c0 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
2e3d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2e3e0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
2e3f0 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
2e400 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2e410 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2e420 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
2e430 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
2e440 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
2e450 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2e460 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
2e470 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2e480 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  n is running..**
2e490 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2e4a0 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 31 7d 20 54  **.** {H16211} T
2e4b0 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74  he first invocat
2e4c0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
2e4d0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2e4e0 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20  t(C,N)] for.**  
2e4f0 20 20 20 20 20 20 20 20 61 20 70 61 72 74 69 63          a partic
2e500 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66  ular instance of
2e510 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 66 75   an aggregate fu
2e520 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61  nction (for a pa
2e530 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20  rticular.**     
2e540 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20       context C) 
2e550 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
2e560 20 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74 65   allocate N byte
2e570 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  s of memory,.** 
2e580 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68           zero th
2e590 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
2e5a0 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20  eturn a pointer 
2e5b0 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  to the allocated
2e5c0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b   memory..**.** {
2e5d0 48 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d  H16213} If a mem
2e5e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2e5f0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
2e600 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
2e610 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2e620 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20  e_context(C,N)] 
2e630 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  then the functio
2e640 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a  n returns 0..**.
2e650 2a 2a 20 7b 48 31 36 32 31 35 7d 20 53 65 63 6f  ** {H16215} Seco
2e660 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
2e670 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  t invocations of
2e680 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2e690 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2e6a0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f  context(C,N)] fo
2e6b0 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65  r the same conte
2e6c0 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20  xt pointer C.** 
2e6d0 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20           ignore 
2e6e0 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
2e6f0 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69  and return a poi
2e700 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65  nter to the same
2e710 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f  .**          blo
2e720 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74  ck of memory ret
2e730 75 72 6e 65 64 20 62 79 20 74 68 65 20 66 69 72  urned by the fir
2e740 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  st invocation..*
2e750 2a 0a 2a 2a 20 7b 48 31 36 32 31 37 7d 20 54 68  *.** {H16217} Th
2e760 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
2e770 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61  ed by [sqlite3_a
2e780 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2e790 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20  (C,N)] is.**    
2e7a0 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61        automatica
2e7b0 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65  lly freed on the
2e7c0 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73   next call to [s
2e7d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
2e7e0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
2e7f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e800 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65  ()] for the [pre
2e810 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e820 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20   containing.**  
2e830 20 20 20 20 20 20 20 20 74 68 65 20 61 67 67 72          the aggr
2e840 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61  egate function a
2e850 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63  ssociated with c
2e860 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69  ontext C..*/.voi
2e870 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
2e880 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
2e890 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2e8a0 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
2e8b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
2e8c0 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
2e8d0 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c 53  ions {H16240} <S
2e8e0 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
2e8f0 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
2e900 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
2e910 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2e920 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
2e930 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
2e940 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
2e950 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
2e960 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
2e970 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2e980 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
2e990 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2e9a0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
2e9b0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
2e9c0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
2e9d0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
2e9e0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2e9f0 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a  unction. {END}.*
2ea00 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
2ea10 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
2ea20 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
2ea30 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
2ea40 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
2ea50 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2ea60 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2ea70 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2ea80 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d 20  .**.** {H16243} 
2ea90 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  The [sqlite3_use
2eaa0 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65 72  r_data(C)] inter
2eab0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
2eac0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  opy of the.**   
2ead0 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65 72         P pointer
2eae0 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
2eaf0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2eb00 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53  on(D,X,N,E,P,F,S
2eb10 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,L)].**         
2eb20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   or [sqlite3_cre
2eb30 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44  ate_function16(D
2eb40 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
2eb50 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20   call that.**   
2eb60 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
2eb70 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
2eb80 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  on associated wi
2eb90 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  th [sqlite3_cont
2eba0 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20  ext] C..*/.void 
2ebb0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
2ebc0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
2ebd0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
2ebe0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
2ebf0 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
2ec00 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 30  unctions {H16250
2ec10 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 30  } <S60600><S2020
2ec20 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
2ec30 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2ec40 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
2ec50 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
2ec60 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
2ec70 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
2ec80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2ec90 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
2eca0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
2ecb0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2ecc0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
2ecd0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2ece0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
2ecf0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
2ed00 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
2ed10 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
2ed20 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2ed30 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
2ed40 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2ed50 20 7b 48 31 36 32 35 33 7d 20 54 68 65 20 5b 73   {H16253} The [s
2ed60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2ed70 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74  b_handle(C)] int
2ed80 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2ed90 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2eda0 20 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e 74           D point
2edb0 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  er from the [sql
2edc0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2edd0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
2ede0 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,S,L)].**       
2edf0 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63     or [sqlite3_c
2ee00 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2ee10 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
2ee20 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20  )] call that.** 
2ee30 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
2ee40 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  red the SQL func
2ee50 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20  tion associated 
2ee60 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f  with [sqlite3_co
2ee70 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c  ntext] C..*/.sql
2ee80 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
2ee90 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2eea0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2eeb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2eec0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
2eed0 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31 36  iliary Data {H16
2eee0 32 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  270} <S20200>.**
2eef0 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
2ef00 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  g two functions 
2ef10 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73  may be used by s
2ef20 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
2ef30 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
2ef40 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
2ef50 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
2ef60 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
2ef70 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
2ef80 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
2ef90 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
2efa0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
2efb0 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
2efc0 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
2efd0 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
2efe0 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
2eff0 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
2f000 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
2f010 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20   This may.** be 
2f020 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
2f030 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75  e, to add a regu
2f040 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
2f050 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a  atching scalar.*
2f060 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
2f070 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
2f080 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
2f090 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74  expression is st
2f0a0 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64  ored as.** metad
2f0b0 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
2f0c0 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75  ith the SQL valu
2f0d0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2f0e0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
2f0f0 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20  on.** pattern.  
2f100 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  The compiled reg
2f110 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
2f120 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
2f130 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
2f140 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
2f150 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f  same function so
2f160 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e   that the origin
2f170 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  al pattern strin
2f180 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65  g.** does not ne
2f190 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69  ed to be recompi
2f1a0 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f  led on each invo
2f1b0 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  cation..**.** Th
2f1c0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
2f1d0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
2f1e0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2f1f0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
2f200 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
2f210 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
2f220 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
2f230 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
2f240 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
2f250 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
2f260 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2f270 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e  d function. If n
2f280 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  o metadata has b
2f290 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e  een ever.** been
2f2a0 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68   set for the Nth
2f2b0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
2f2c0 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
2f2d0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2f2e0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  ng.** function p
2f2f0 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61  arameter has cha
2f300 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
2f310 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
2f320 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  ,.** then sqlite
2f330 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
2f340 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
2f350 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
2f360 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
2f370 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
2f380 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
2f390 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  data.** pointed 
2f3a0 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61  to by its 3rd pa
2f3b0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d  rameter as the m
2f3c0 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20  etadata for the 
2f3d0 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
2f3e0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2f3f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2f400 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e  tion.  Subsequen
2f410 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
2f420 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2f430 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e  a() might return
2f440 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69   this data, if i
2f450 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65  t has.** not bee
2f460 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20  n destroyed..** 
2f470 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  If it is not NUL
2f480 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  L, SQLite will i
2f490 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2f4a0 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ctor.** function
2f4b0 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74   given by the 4t
2f4c0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2f4d0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2f4e0 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d  ta() on.** the m
2f4f0 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65  etadata when the
2f500 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
2f510 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
2f520 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20  r changes.** or 
2f530 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  when the SQL sta
2f540 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73  tement completes
2f550 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
2f560 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  s first..**.** S
2f570 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
2f580 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75   call the destru
2f590 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65  ctor and drop me
2f5a0 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a  tadata on any.**
2f5b0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e   parameter of an
2f5c0 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e  y function at an
2f5d0 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c  y time.  The onl
2f5e0 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74  y guarantee is t
2f5f0 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72  hat.** the destr
2f600 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61  uctor will be ca
2f610 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  lled before the 
2f620 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70  metadata is drop
2f630 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72  ped..**.** In pr
2f640 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61  actice, metadata
2f650 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
2f660 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
2f670 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72  alls for.** expr
2f680 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65  essions that are
2f690 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d   constant at com
2f6a0 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20  pile time. This 
2f6b0 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c  includes literal
2f6c0 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53  .** values and S
2f6d0 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a  QL variables..**
2f6e0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2f6f0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
2f700 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2f710 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2f720 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
2f730 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2f740 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2f750 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 32 7d  :.**.** {H16272}
2f760 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65   The [sqlite3_ge
2f770 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d 20  t_auxdata(C,N)] 
2f780 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2f790 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20  s a pointer.**  
2f7a0 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61 64          to metad
2f7b0 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
2f7c0 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72 61  ith the Nth para
2f7d0 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c  meter of the SQL
2f7e0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2f7f0 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e 74        whose cont
2f800 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c  ext is C, or NUL
2f810 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f  L if there is no
2f820 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
2f830 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
2f840 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61 6d   with that param
2f850 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  eter..**.** {H16
2f860 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  274} The [sqlite
2f870 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
2f880 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  N,P,D)] interfac
2f890 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74 61  e assigns a meta
2f8a0 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  data.**         
2f8b0 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 68   pointer P to th
2f8c0 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20  e Nth parameter 
2f8d0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
2f8e0 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 74  ion with context
2f8f0 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37   C..**.** {H1627
2f900 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  6} SQLite will i
2f910 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2f920 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73 69  ctor D with a si
2f930 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ngle argument.**
2f940 20 20 20 20 20 20 20 20 20 20 77 68 69 63 68 20            which 
2f950 69 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  is the metadata 
2f960 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77  pointer P follow
2f970 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ing a call to.**
2f980 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2f990 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
2f9a0 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 51  ,N,P,D)] when SQ
2f9b0 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68  Lite ceases to h
2f9c0 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  old.**          
2f9d0 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a  the metadata..**
2f9e0 0a 2a 2a 20 7b 48 31 36 32 37 37 7d 20 53 51 4c  .** {H16277} SQL
2f9f0 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f  ite ceases to ho
2fa00 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  ld metadata for 
2fa10 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
2fa20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
2fa30 20 20 20 20 20 20 77 68 65 6e 20 74 68 65 20 76        when the v
2fa40 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61 72  alue of that par
2fa50 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e 0a  ameter changes..
2fa60 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 38 7d 20 57  **.** {H16278} W
2fa70 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  hen [sqlite3_set
2fa80 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44  _auxdata(C,N,P,D
2fa90 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  )] is invoked, t
2faa0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
2fab0 20 20 20 20 20 20 20 20 20 20 69 73 20 63 61 6c            is cal
2fac0 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69 6f  led for any prio
2fad0 72 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  r metadata assoc
2fae0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73  iated with the s
2faf0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ame function.** 
2fb00 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74           context
2fb10 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72   C and parameter
2fb20 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37   N..**.** {H1627
2fb30 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63  9} SQLite will c
2fb40 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73 20  all destructors 
2fb50 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74 61  for any metadata
2fb60 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a   it is holding.*
2fb70 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61 20  *          in a 
2fb80 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65 70  particular [prep
2fb90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2fba0 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a  S when either.**
2fbb0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2fbc0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 20  e3_reset(S)] or 
2fbd0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2fbe0 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  e(S)] is called.
2fbf0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2fc00 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
2fc10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2fc20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c  int N);.void sql
2fc30 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2fc40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2fc50 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c  *, int N, void*,
2fc60 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29   void (*)(void*)
2fc70 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
2fc80 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44  REF: Constants D
2fc90 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20  efining Special 
2fca0 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76  Destructor Behav
2fcb0 69 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c 53 33  ior {H10280} <S3
2fcc0 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0100>.**.** Thes
2fcd0 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
2fce0 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
2fcf0 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
2fd00 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
2fd10 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
2fd20 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
2fd30 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
2fd40 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66  ult_blob()].  If
2fd50 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
2fd60 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53  ** argument is S
2fd70 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74  QLITE_STATIC, it
2fd80 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2fd90 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20  content pointer 
2fda0 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61  is constant.** a
2fdb0 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68  nd will never ch
2fdc0 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e  ange.  It does n
2fdd0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65  ot need to be de
2fde0 73 74 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a  stroyed.  The.**
2fdf0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
2fe00 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68  T value means th
2fe10 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77  at the content w
2fe20 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67  ill likely chang
2fe30 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72  e in.** the near
2fe40 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74   future and that
2fe50 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d   SQLite should m
2fe60 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76  ake its own priv
2fe70 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  ate copy of.** t
2fe80 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72  he content befor
2fe90 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
2fea0 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69  ** The typedef i
2feb0 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77  s necessary to w
2fec0 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c  ork around probl
2fed0 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a  ems in certain.*
2fee0 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e  * C++ compilers.
2fef0 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31    See ticket #21
2ff00 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  91..*/.typedef v
2ff10 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
2ff20 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
2ff30 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
2ff40 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
2ff50 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
2ff60 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
2ff70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
2ff80 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
2ff90 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
2ffa0 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
2ffb0 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
2ffc0 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
2ffd0 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b  n SQL Function {
2ffe0 48 31 36 34 30 30 7d 20 3c 53 32 30 32 30 30 3e  H16400} <S20200>
2fff0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
30000 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
30010 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
30020 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
30030 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
30040 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
30050 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
30060 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
30070 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30080 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
30090 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
300a0 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
300b0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
300c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
300d0 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
300e0 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
300f0 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69  he [parameter bi
30100 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66  nding] family of
30110 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  .** functions us
30120 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ed to bind value
30130 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
30140 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
30150 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
30160 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51  Refer to the [SQ
30170 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63  L parameter] doc
30180 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
30190 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
301a0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
301b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
301c0 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
301d0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
301e0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
301f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30200 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
30210 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f  he BLOB whose co
30220 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64  ntent is pointed
30230 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65  .** to by the se
30240 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61  cond parameter a
30250 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79  nd which is N by
30260 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e  tes long where N
30270 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64   is the.** third
30280 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
30290 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
302a0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  sult_zeroblob() 
302b0 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74  interfaces set t
302c0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
302d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
302e0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
302f0 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f   to be a BLOB co
30300 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72  ntaining all zer
30310 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e  o.** bytes and N
30320 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20   bytes in size, 
30330 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
30340 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20  alue of the 2nd 
30350 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
30360 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
30370 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
30380 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
30390 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
303a0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
303b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
303c0 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
303d0 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
303e0 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
303f0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
30400 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
30410 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
30420 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
30430 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
30440 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
30450 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
30460 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
30470 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
30480 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  n..** SQLite use
30490 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69  s the string poi
304a0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a  nted to by the.*
304b0 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
304c0 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  of sqlite3_resul
304d0 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c  t_error() or sql
304e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
304f0 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20  r16().** as the 
30500 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  text of an error
30510 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74   message.  SQLit
30520 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
30530 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
30540 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
30550 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30560 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 53  or() as UTF-8. S
30570 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
30580 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
30590 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
305a0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
305b0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
305c0 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
305d0 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61   If the third pa
305e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
305f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
30600 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
30610 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
30620 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
30630 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
30640 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
30650 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
30660 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
30670 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
30680 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74  ter..** If the t
30690 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
306a0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
306b0 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
306c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
306d0 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
306e0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
306f0 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
30700 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
30710 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
30720 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
30730 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
30740 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68  r message..** Th
30750 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30760 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
30770 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30780 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
30790 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
307a0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
307b0 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
307c0 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
307d0 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
307e0 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
307f0 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
30800 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
30810 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
30820 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
30830 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20  ut harm..** The 
30840 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30850 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63  rror_code() func
30860 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65  tion changes the
30870 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72   error code.** r
30880 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74  eturned by SQLit
30890 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66  e as a result of
308a0 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66   an error in a f
308b0 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66  unction.  By def
308c0 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
308d0 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
308e0 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73  E_ERROR.  A subs
308f0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
30900 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30910 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
30920 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30930 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20  16() resets the 
30940 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51  error code to SQ
30950 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a  LITE_ERROR..**.*
30960 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
30970 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e  sult_toobig() in
30980 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
30990 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
309a0 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63  n error.** indic
309b0 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
309c0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
309d0 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73  o long to repres
309e0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
309f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f  qlite3_result_no
30a00 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
30a10 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
30a20 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
30a30 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
30a40 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
30a50 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
30a60 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
30a70 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e  _result_int() in
30a80 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
30a90 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
30aa0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
30ab0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
30ac0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33  tion to be the 3
30ad0 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
30ae0 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
30af0 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
30b00 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
30b10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
30b20 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  nt64() interface
30b30 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
30b40 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
30b50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30b60 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
30b70 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73   be the 64-bit s
30b80 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
30b90 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
30ba0 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
30bb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
30bc0 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
30bd0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
30be0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
30bf0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
30c00 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30c10 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
30c20 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ULL..**.** The s
30c30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
30c40 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  xt(), sqlite3_re
30c50 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a  sult_text16(),.*
30c60 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
30c70 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64  _text16le(), and
30c80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30c90 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72  text16be() inter
30ca0 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65  faces.** set the
30cb0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
30cc0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30cd0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
30ce0 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78  n to be.** a tex
30cf0 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  t string which i
30d00 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73  s represented as
30d10 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e   UTF-8, UTF-16 n
30d20 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
30d30 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
30d40 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le endian, or UT
30d50 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c  F-16 big endian,
30d60 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
30d70 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  * SQLite takes t
30d80 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66  he text result f
30d90 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74  rom the applicat
30da0 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ion from.** the 
30db0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
30dc0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
30dd0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
30de0 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  aces..** If the 
30df0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
30e00 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
30e10 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
30e20 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
30e30 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
30e40 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
30e50 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
30e60 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
30e70 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
30e80 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
30e90 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
30ea0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
30eb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
30ec0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
30ed0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
30ee0 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
30ef0 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
30f00 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
30f10 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
30f20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
30f30 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
30f40 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
30f50 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
30f60 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a  ction result..**
30f70 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
30f80 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
30f90 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
30fa0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
30fb0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
30fc0 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d  t_blob is a non-
30fd0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
30fe0 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20  en SQLite calls 
30ff0 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  that.** function
31000 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74   as the destruct
31010 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f  or on the text o
31020 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68  r BLOB result wh
31030 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
31040 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
31050 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74   result..** If t
31060 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
31070 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
31080 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
31090 65 72 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73 71  erfaces or.** sq
310a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
310b0 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
310c0 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
310d0 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
310e0 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
310f0 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
31100 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
31110 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
31120 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
31130 2a 20 63 6f 70 79 20 74 68 65 20 69 74 20 6f 72  * copy the it or
31140 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
31150 6f 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  or when it has f
31160 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
31170 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66  at result..** If
31180 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
31190 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
311a0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
311b0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
311c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
311d0 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
311e0 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
311f0 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
31200 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
31210 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
31220 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
31230 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
31240 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
31250 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
31260 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
31270 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
31280 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
31290 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
312a0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
312b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
312c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
312d0 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
312e0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
312f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
31300 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
31310 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
31320 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73  meter.  The.** s
31330 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
31340 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
31350 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
31360 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
31370 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74  ue].** so that t
31380 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
31390 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  e] specified in 
313a0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  the parameter ma
313b0 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62  y change or.** b
313c0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66  e deallocated af
313d0 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ter sqlite3_resu
313e0 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72  lt_value() retur
313f0 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  ns without harm.
31400 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64  .** A [protected
31410 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
31420 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
31430 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
31440 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
31450 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31460 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
31470 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
31480 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
31490 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
314a0 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
314b0 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
314c0 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
314d0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
314e0 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
314f0 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
31500 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
31510 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
31520 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
31530 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
31540 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
31550 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
31560 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
31570 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
31580 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
31590 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
315a0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 33 7d 20 54  **.** {H16403} T
315b0 68 65 20 64 65 66 61 75 6c 74 20 72 65 74 75 72  he default retur
315c0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79  n value from any
315d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
315e0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   NULL..**.** {H1
315f0 36 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  6406} The [sqlit
31600 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43  e3_result_blob(C
31610 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,V,N,D)] interfa
31620 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
31630 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
31640 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
31650 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 42 4c  ion C to be a BL
31660 4f 42 20 74 68 61 74 20 69 73 20 4e 20 62 79 74  OB that is N byt
31670 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  es.**          i
31680 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 74  n length and wit
31690 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  h content pointe
316a0 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a  d to by V..**.**
316b0 20 7b 48 31 36 34 30 39 7d 20 54 68 65 20 5b 73   {H16409} The [s
316c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
316d0 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 72  uble(C,V)] inter
316e0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
316f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
31700 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
31710 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
31720 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
31730 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20   value V..**.** 
31740 7b 48 31 36 34 31 32 7d 20 54 68 65 20 5b 73 71  {H16412} The [sq
31750 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31760 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72  or(C,V,N)] inter
31770 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
31780 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
31790 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e      value of fun
317a0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
317b0 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
317c0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
317d0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45         [SQLITE_E
317e0 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d  RROR] and a UTF-
317f0 38 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  8 error message 
31800 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70  copied from V up
31810 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
31820 20 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20 62      first zero b
31830 79 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62  yte or until N b
31840 79 74 65 73 20 61 72 65 20 72 65 61 64 20 69 66  ytes are read if
31850 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a   N is positive..
31860 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 35 7d 20 54  **.** {H16415} T
31870 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
31880 6c 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e  lt_error16(C,V,N
31890 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
318a0 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a  nges the return.
318b0 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
318c0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
318d0 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69  to be an excepti
318e0 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f  on with error co
318f0 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  de.**          [
31900 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e  SQLITE_ERROR] an
31910 64 20 61 20 55 54 46 2d 31 36 20 6e 61 74 69 76  d a UTF-16 nativ
31920 65 20 62 79 74 65 20 6f 72 64 65 72 20 65 72 72  e byte order err
31930 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20  or message.**   
31940 20 20 20 20 20 20 20 63 6f 70 69 65 64 20 66 72         copied fr
31950 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 20 66  om V up to the f
31960 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
31970 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e 20  ator or until N 
31980 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  bytes.**        
31990 20 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20    are read if N 
319a0 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a  is positive..**.
319b0 2a 2a 20 7b 48 31 36 34 31 38 7d 20 54 68 65 20  ** {H16418} The 
319c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
319d0 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29 5d  error_toobig(C)]
319e0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
319f0 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
31a00 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
31a10 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
31a20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
31a30 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
31a40 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
31a50 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d   [SQLITE_TOOBIG]
31a60 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69   and an appropri
31a70 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ate error messag
31a80 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 31  e..**.** {H16421
31a90 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
31aa0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
31ab0 6d 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20  m(C)] interface 
31ac0 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75  changes the retu
31ad0 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  rn.**          v
31ae0 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63  alue of the func
31af0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
31b00 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
31b10 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20  rror code.**    
31b20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e 4f        [SQLITE_NO
31b30 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70 72  MEM] and an appr
31b40 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65  opriate error me
31b50 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ssage..**.** {H1
31b60 36 34 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  6424} The [sqlit
31b70 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
31b80 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74 65 72  code(C,E)] inter
31b90 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
31ba0 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
31bb0 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65      value of the
31bc0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
31bd0 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77  e an exception w
31be0 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 20 45  ith error code E
31bf0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 54 68  ..**          Th
31c00 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
31c10 74 65 78 74 20 69 73 20 75 6e 63 68 61 6e 67 65  text is unchange
31c20 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 37  d..**.** {H16427
31c30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
31c40 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20  esult_int(C,V)] 
31c50 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
31c60 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
31c70 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
31c80 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
31c90 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 69 6e  be the 32-bit in
31ca0 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a  teger value V..*
31cb0 2a 0a 2a 2a 20 7b 48 31 36 34 33 30 7d 20 54 68  *.** {H16430} Th
31cc0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
31cd0 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20 69 6e  t_int64(C,V)] in
31ce0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
31cf0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
31d00 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
31d10 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
31d20 20 74 68 65 20 36 34 2d 62 69 74 20 69 6e 74 65   the 64-bit inte
31d30 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a  ger value V..**.
31d40 2a 2a 20 7b 48 31 36 34 33 33 7d 20 54 68 65 20  ** {H16433} The 
31d50 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
31d60 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66 61  null(C)] interfa
31d70 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
31d80 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
31d90 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
31da0 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c 4c  ion C to be NULL
31db0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 36 7d  ..**.** {H16436}
31dc0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
31dd0 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c  sult_text(C,V,N,
31de0 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  D)] interface ch
31df0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
31e00 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
31e10 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
31e20 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 38   to be the UTF-8
31e30 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20   string.**      
31e40 20 20 20 20 56 20 75 70 20 74 6f 20 74 68 65 20      V up to the 
31e50 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20  first zero if N 
31e60 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20  is negative.**  
31e70 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66          or the f
31e80 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20  irst N bytes of 
31e90 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  V if N is non-ne
31ea0 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  gative..**.** {H
31eb0 31 36 34 33 39 7d 20 54 68 65 20 5b 73 71 6c 69  16439} The [sqli
31ec0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
31ed0 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65  6(C,V,N,D)] inte
31ee0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
31ef0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
31f00 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
31f10 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
31f20 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  he UTF-16 native
31f30 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20   byte order.**  
31f40 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56          string V
31f50 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
31f60 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65   zero if N is ne
31f70 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  gative.**       
31f80 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20     or the first 
31f90 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20  N bytes of V if 
31fa0 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
31fb0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 32  e..**.** {H16442
31fc0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
31fd0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43  esult_text16be(C
31fe0 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,V,N,D)] interfa
31ff0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
32000 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
32010 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
32020 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
32030 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
32040 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
32050 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
32060 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
32070 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
32080 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
32090 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 72  first N bytes or
320a0 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
320b0 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
320c0 48 31 36 34 34 35 7d 20 54 68 65 20 5b 73 71 6c  H16445} The [sql
320d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
320e0 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16le(C,V,N,D)] i
320f0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
32100 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
32110 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
32120 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
32130 65 20 74 68 65 20 55 54 46 2d 31 36 20 6c 69 74  e the UTF-16 lit
32140 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20  tle-endian.**   
32150 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20         string V 
32160 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
32170 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67  zero if N is neg
32180 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
32190 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e    or the first N
321a0 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e   bytes of V if N
321b0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
321c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 38 7d  ..**.** {H16448}
321d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
321e0 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29 5d  sult_value(C,V)]
321f0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
32200 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
32210 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
32220 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
32230 20 62 65 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   be the [unprote
32240 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
32250 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ue].**          
32260 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20  object V..**.** 
32270 7b 48 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71  {H16451} The [sq
32280 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
32290 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65  oblob(C,N)] inte
322a0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
322b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
322c0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
322d0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
322e0 6e 20 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f 66  n N-byte BLOB of
322f0 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a   all zeros..**.*
32300 2a 20 7b 48 31 36 34 35 34 7d 20 54 68 65 20 5b  * {H16454} The [
32310 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32320 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c  rror()] and [sql
32330 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32340 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  r16()].**       
32350 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61     interfaces ma
32360 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ke a copy of the
32370 69 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ir error message
32380 20 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a   strings before.
32390 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
323a0 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  rning..**.** {H1
323b0 36 34 35 37 7d 20 49 66 20 74 68 65 20 44 20 64  6457} If the D d
323c0 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65  estructor parame
323d0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
323e0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c  result_blob(C,V,
323f0 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
32400 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
32410 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29  lt_text(C,V,N,D)
32420 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ], [sqlite3_resu
32430 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c  lt_text16(C,V,N,
32440 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
32450 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32460 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c  _text16be(C,V,N,
32470 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
32480 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
32490 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56  ult_text16le(C,V
324a0 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f  ,N,D)] is the co
324b0 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53  nstant [SQLITE_S
324c0 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20  TATIC].**       
324d0 20 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72     then no destr
324e0 75 63 74 6f 72 20 69 73 20 65 76 65 72 20 63 61  uctor is ever ca
324f0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e  lled on the poin
32500 74 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65  ter V and SQLite
32510 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73  .**          ass
32520 75 6d 65 73 20 74 68 61 74 20 56 20 69 73 20 69  umes that V is i
32530 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  mmutable..**.** 
32540 7b 48 31 36 34 36 30 7d 20 49 66 20 74 68 65 20  {H16460} If the 
32550 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72  D destructor par
32560 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
32570 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43  e3_result_blob(C
32580 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
32590 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
325a0 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
325b0 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72  ,D)], [sqlite3_r
325c0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56  esult_text16(C,V
325d0 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
325e0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
325f0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56  ult_text16be(C,V
32600 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,N,D)], or.**   
32610 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
32620 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
32630 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65  C,V,N,D)] is the
32640 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20   constant.**    
32650 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52        [SQLITE_TR
32660 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68  ANSIENT] then th
32670 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b  e interfaces mak
32680 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
32690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
326a0 74 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65  tent of V and re
326b0 74 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a  tains the copy..
326c0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 33 7d 20 49  **.** {H16463} I
326d0 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74  f the D destruct
326e0 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  or parameter to 
326f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32700 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  blob(C,V,N,D)],.
32710 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
32720 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32730 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c  (C,V,N,D)], [sql
32740 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32750 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  16(C,V,N,D)],.**
32760 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
32770 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
32780 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72  be(C,V,N,D)], or
32790 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
327a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
327b0 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
327c0 69 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74  is some value ot
327d0 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
327e0 20 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e       the constan
327f0 74 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ts [SQLITE_STATI
32800 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54  C] and [SQLITE_T
32810 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a 2a  RANSIENT] then.*
32820 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74  *          SQLit
32830 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
32840 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77  e destructor D w
32850 69 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e 6c  ith V as its onl
32860 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20  y argument.**   
32870 20 20 20 20 20 20 20 77 68 65 6e 20 69 74 20 68         when it h
32880 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
32890 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f   the V value..*/
328a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
328b0 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
328c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
328d0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
328e0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
328f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32900 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
32910 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
32920 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  le);.void sqlite
32930 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73  3_result_error(s
32940 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32950 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
32960 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
32970 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
32980 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32990 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
329a0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
329b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
329c0 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
329d0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
329e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
329f0 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
32a00 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
32a10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32a20 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
32a30 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
32a40 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
32a50 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74  result_int(sqlit
32a60 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
32a70 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
32a80 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c  result_int64(sql
32a90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
32aa0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76  qlite3_int64);.v
32ab0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32ac0 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
32ad0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
32ae0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32af0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
32b00 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
32b10 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
32b20 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
32b30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32b40 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
32b50 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
32b60 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
32b70 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
32b80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32b90 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
32ba0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
32bb0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
32bc0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
32bd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32be0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
32bf0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
32c00 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
32c10 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
32c20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
32c30 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
32c40 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
32c50 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
32c60 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
32c70 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
32c80 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
32c90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32ca0 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
32cb0 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b  ting Sequences {
32cc0 48 31 36 36 30 30 7d 20 3c 53 32 30 33 30 30 3e  H16600} <S20300>
32cd0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
32ce0 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20  ctions are used 
32cf0 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61  to add new colla
32d00 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74  tion sequences t
32d10 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  o the.** [databa
32d20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
32d30 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
32d40 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
32d50 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f  **.** The name o
32d60 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74  f the new collat
32d70 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20  ion sequence is 
32d80 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20 55  specified as a U
32d90 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66  TF-8 string.** f
32da0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
32db0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e  e_collation() an
32dc0 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  d sqlite3_create
32dd0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a  _collation_v2().
32de0 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20  ** and a UTF-16 
32df0 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74  string for sqlit
32e00 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32e10 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20  ion16(). In all 
32e20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  cases.** the nam
32e30 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74  e is passed as t
32e40 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
32e50 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
32e60 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67  ** The third arg
32e70 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65  ument may be one
32e80 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
32e90 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  s [SQLITE_UTF8],
32ea0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
32eb0 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  6LE] or [SQLITE_
32ec0 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61  UTF16BE], indica
32ed0 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 73  ting that the us
32ee0 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72  er-supplied.** r
32ef0 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74  outine expects t
32f00 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e  o be passed poin
32f10 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
32f20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
32f30 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  F-8,.** UTF-16 l
32f40 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72  ittle-endian, or
32f50 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69   UTF-16 big-endi
32f60 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
32f70 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61  . The.** third a
32f80 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c  rgument might al
32f90 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54  so be [SQLITE_UT
32fa0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20  F16_ALIGNED] to 
32fb0 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a 2a  indicate that.**
32fc0 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70   the routine exp
32fd0 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f  ects pointers to
32fe0 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69   16-bit word ali
32ff0 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  gned strings.** 
33000 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  of UTF-16 in the
33010 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
33020 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 63  er of the host c
33030 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  omputer..**.** A
33040 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
33050 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f  user supplied ro
33060 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61  utine must be pa
33070 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74  ssed as the fift
33080 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  h.** argument.  
33090 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
330a0 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20  his is the same 
330b0 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  as deleting the 
330c0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
330d0 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53  uence (so that S
330e0 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c  QLite cannot cal
330f0 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a  l it anymore)..*
33100 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20  * Each time the 
33110 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70  application supp
33120 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  lied function is
33130 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20   invoked, it is 
33140 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73  passed.** as its
33150 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
33160 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
33170 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 74  oid* passed as t
33180 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
33190 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
331a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
331b0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
331c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
331d0 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72  6()..**.** The r
331e0 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e  emaining argumen
331f0 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ts to the applic
33200 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72  ation-supplied r
33210 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73  outine are two s
33220 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20  trings,.** each 
33230 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
33240 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20   (length, data) 
33250 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64  pair and encoded
33260 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
33270 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73  .** that was pas
33280 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
33290 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74   argument when t
332a0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  he collation seq
332b0 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67  uence was.** reg
332c0 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20  istered. {END}  
332d0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
332e0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
332f0 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  n routine should
33300 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74  .** return negat
33310 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73  ive, zero or pos
33320 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69 72  itive if the fir
33330 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73  st string is les
33340 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c  s than,.** equal
33350 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
33360 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20  than the second 
33370 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54  string. i.e. (ST
33380 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29  RING1 - STRING2)
33390 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
333a0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
333b0 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
333c0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
333d0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
333e0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
333f0 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61  t takes an extra
33400 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
33410 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
33420 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  for.** the colla
33430 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72  tion.  The destr
33440 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20  uctor is called 
33450 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  when the collati
33460 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79  on is.** destroy
33470 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64  ed and is passed
33480 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
33490 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
334a0 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a  void* pointer.**
334b0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
334c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
334d0 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74  _v2()..** Collat
334e0 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79  ions are destroy
334f0 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65  ed when they are
33500 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
33510 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68  ater calls to th
33520 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63  e.** collation c
33530 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  reation function
33540 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64  s or when the [d
33550 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33560 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a  on] is closed.**
33570 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
33580 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
33590 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
335a0 2a 20 7b 48 31 36 36 30 33 7d 20 41 20 73 75 63  * {H16603} A suc
335b0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
335c0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
335d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
335e0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
335f0 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65 72  ,E,P,F,D)] inter
33600 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  face.**         
33610 20 72 65 67 69 73 74 65 72 73 20 66 75 6e 63 74   registers funct
33620 69 6f 6e 20 46 20 61 73 20 74 68 65 20 63 6f 6d  ion F as the com
33630 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e  parison function
33640 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20   used to.**     
33650 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20 63       implement c
33660 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74 68  ollation X on th
33670 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
33680 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a  ection] B for.**
33690 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61            databa
336a0 73 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f 64  ses having encod
336b0 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ing E..**.** {H1
336c0 36 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 64  6604} SQLite und
336d0 65 72 73 74 61 6e 64 73 20 74 68 65 20 58 20 70  erstands the X p
336e0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20  arameter to.**  
336f0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
33700 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
33710 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
33720 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72  )] as a zero-ter
33730 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  minated.**      
33740 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67      UTF-8 string
33750 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 69   in which case i
33760 73 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 53  s ignored for AS
33770 43 49 49 20 63 68 61 72 61 63 74 65 72 73 20 61  CII characters a
33780 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  nd.**          i
33790 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66 6f  s significant fo
337a0 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 72  r non-ASCII char
337b0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  acters..**.** {H
337c0 31 36 36 30 36 7d 20 53 75 63 63 65 73 73 69 76  16606} Successiv
337d0 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
337e0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
337f0 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
33800 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  F,D)].**        
33810 20 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20    with the same 
33820 76 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 2c  values for B, X,
33830 20 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 65   and E, override
33840 20 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a 2a   prior values.**
33850 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c 20            of P, 
33860 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20  F, and D..**.** 
33870 7b 48 31 36 36 30 39 7d 20 49 66 20 74 68 65 20  {H16609} If the 
33880 64 65 73 74 72 75 63 74 6f 72 20 44 20 69 6e 20  destructor D in 
33890 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
338a0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
338b0 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20  ,E,P,F,D)].**   
338c0 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20 4e 55         is not NU
338d0 4c 4c 20 74 68 65 6e 20 69 74 20 69 73 20 63 61  LL then it is ca
338e0 6c 6c 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  lled with argume
338f0 6e 74 20 50 20 77 68 65 6e 20 74 68 65 0a 2a 2a  nt P when the.**
33900 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74            collat
33910 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
33920 64 72 6f 70 70 65 64 20 62 79 20 53 51 4c 69 74  dropped by SQLit
33930 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 32  e..**.** {H16612
33940 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  } A collating fu
33950 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65  nction is droppe
33960 64 20 77 68 65 6e 20 69 74 20 69 73 20 6f 76 65  d when it is ove
33970 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  rloaded..**.** {
33980 48 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61 74  H16615} A collat
33990 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
339a0 64 72 6f 70 70 65 64 20 77 68 65 6e 20 74 68 65  dropped when the
339b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
339c0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
339d0 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
339e0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
339f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31  )]..**.** {H1661
33a00 38 7d 20 54 68 65 20 70 6f 69 6e 74 65 72 20 50  8} The pointer P
33a10 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   in [sqlite3_cre
33a20 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33a30 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a  (B,X,E,P,F,D)].*
33a40 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70 61  *          is pa
33a50 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
33a60 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
33a70 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6d 70 61  ter to the compa
33a80 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  rison.**        
33a90 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72    function F for
33aa0 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
33ab0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 46  invocations of F
33ac0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 31 7d  ..**.** {H16621}
33ad0 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   A call to [sqli
33ae0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33af0 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d  tion(B,X,E,P,F)]
33b00 20 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20   is exactly.**  
33b10 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
33b20 20 61 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   as a call to [s
33b30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33b40 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77 69  llation_v2()] wi
33b50 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
33b60 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65  he same paramete
33b70 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64 65  rs and a NULL de
33b80 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  structor..**.** 
33b90 7b 48 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 69  {H16624} Followi
33ba0 6e 67 20 61 20 5b 73 71 6c 69 74 65 33 5f 63 72  ng a [sqlite3_cr
33bb0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
33bc0 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c  2(B,X,E,P,F,D)],
33bd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
33be0 69 74 65 20 75 73 65 73 20 74 68 65 20 63 6f 6d  ite uses the com
33bf0 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e  parison function
33c00 20 46 20 66 6f 72 20 61 6c 6c 20 74 65 78 74 20   F for all text 
33c10 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20  comparison.**   
33c20 20 20 20 20 20 20 20 6f 70 65 72 61 74 69 6f 6e         operation
33c30 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  s on the [databa
33c40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42  se connection] B
33c50 20 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73 20   on text values 
33c60 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
33c70 20 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 69   use the collati
33c80 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  ng sequence name
33c90 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  d X..**.** {H166
33ca0 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  27} The [sqlite3
33cb0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
33cc0 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20  n16(B,X,E,P,F)] 
33cd0 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a  works the same.*
33ce0 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 5b 73  *          as [s
33cf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33d00 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c  llation(B,X,E,P,
33d10 46 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  F)] except that 
33d20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
33d30 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58  collation name X
33d40 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 61   is understood a
33d50 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  s UTF-16 in nati
33d60 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a  ve byte order.**
33d70 20 20 20 20 20 20 20 20 20 20 69 6e 73 74 65 61            instea
33d80 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  d of UTF-8..**.*
33d90 2a 20 7b 48 31 36 36 33 30 7d 20 57 68 65 6e 20  * {H16630} When 
33da0 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 69  multiple compari
33db0 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  son functions ar
33dc0 65 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20  e available for 
33dd0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
33de0 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73       collating s
33df0 65 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 20  equence, SQLite 
33e00 63 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 20  chooses the one 
33e10 77 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f 64  whose text encod
33e20 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
33e30 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61  requires the lea
33e40 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e  st amount of con
33e50 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65  version from the
33e60 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20   default.**     
33e70 20 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64 69       text encodi
33e80 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ng of the databa
33e90 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  se..*/.int sqlit
33ea0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33eb0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
33ec0 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
33ed0 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
33ee0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
33ef0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
33f00 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
33f10 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
33f20 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  st void*).);.int
33f30 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33f40 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20  collation_v2(.  
33f50 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
33f60 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
33f70 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
33f80 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
33f90 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
33fa0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
33fb0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
33fc0 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
33fd0 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
33fe0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
33ff0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a  te_collation16(.
34000 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
34010 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65  onst void *zName
34020 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
34030 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
34040 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
34050 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
34060 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
34070 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
34080 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
34090 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
340a0 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c 53 32 30  ks {H16700} <S20
340b0 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76  300>.**.** To av
340c0 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65  oid having to re
340d0 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61  gister all colla
340e0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62  tion sequences b
340f0 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65  efore a database
34100 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
34110 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61   a single callba
34120 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ck function may 
34130 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  be registered wi
34140 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  th the.** [datab
34150 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
34160 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  to be called whe
34170 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e  never an undefin
34180 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  ed collation.** 
34190 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75  sequence is requ
341a0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ired..**.** If t
341b0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
341c0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
341d0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
341e0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
341f0 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
34200 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
34210 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
34220 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
34230 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
34240 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
34250 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20 49 66 20  -8. {H16703} If 
34260 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
34270 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20  n_needed16() is 
34280 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d  used,.** the nam
34290 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73  es are passed as
342a0 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69   UTF-16 in machi
342b0 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  ne native byte o
342c0 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20  rder..** A call 
342d0 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69  to either functi
342e0 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20  on replaces any 
342f0 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63  existing callbac
34300 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  k..**.** When th
34310 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
34320 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74  voked, the first
34330 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
34340 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66   is a copy.** of
34350 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
34360 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
34370 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
34380 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
34390 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
343a0 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f  d16().  The seco
343b0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
343c0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
343d0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20  onnection.  The 
343e0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
343f0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
34400 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
34410 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20  UTF16BE],.** or 
34420 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
34430 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  , indicating the
34440 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20   most desirable 
34450 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c  form of the coll
34460 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
34470 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  e function requi
34480 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68  red.  The fourth
34490 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
344a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
344b0 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74   required collat
344c0 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a  ion sequence..**
344d0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
344e0 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
344f0 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65   register the de
34500 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  sired collation 
34510 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
34520 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34530 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
34540 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34550 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
34560 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34570 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a  lation_v2()]..**
34580 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
34590 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 32 7d 20 41  **.** {H16702} A
345a0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
345b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
345c0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c  lation_needed(D,
345d0 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  P,F)].**        
345e0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f    or [sqlite3_co
345f0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
34600 28 44 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 0a  (D,P,F)] causes.
34610 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
34620 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34630 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b  tion] D to invok
34640 65 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 74  e callback F wit
34650 68 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20  h first.**      
34660 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 50 20      parameter P 
34670 77 68 65 6e 65 76 65 72 20 69 74 20 6e 65 65 64  whenever it need
34680 73 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66  s a comparison f
34690 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a  unction for a.**
346a0 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74            collat
346b0 69 6e 67 20 73 65 71 75 65 6e 63 65 20 74 68 61  ing sequence tha
346c0 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e  t it does not kn
346d0 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20  ow about..**.** 
346e0 7b 48 31 36 37 30 34 7d 20 45 61 63 68 20 73 75  {H16704} Each su
346f0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
34700 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
34710 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72  ion_needed()] or
34720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
34730 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
34740 6e 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65 72  needed16()] over
34750 72 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62 61  rides the callba
34760 63 6b 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  ck registered.**
34770 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65            on the
34780 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
34790 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70  connection] by p
347a0 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 69  rior calls to ei
347b0 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
347c0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
347d0 2a 20 7b 48 31 36 37 30 36 7d 20 54 68 65 20 6e  * {H16706} The n
347e0 61 6d 65 20 6f 66 20 74 68 65 20 72 65 71 75 65  ame of the reque
347f0 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66  sted collating f
34800 75 6e 63 74 69 6f 6e 20 70 61 73 73 65 64 20 69  unction passed i
34810 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
34820 20 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20    4th parameter 
34830 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
34840 69 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20 74  is in UTF-8 if t
34850 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  he callback.**  
34860 20 20 20 20 20 20 20 20 77 61 73 20 72 65 67 69          was regi
34870 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71  stered using [sq
34880 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
34890 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  needed()] and.**
348a0 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 20            is in 
348b0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
348c0 74 65 20 6f 72 64 65 72 20 69 66 20 74 68 65 20  te order if the 
348d0 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20  callback was.** 
348e0 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
348f0 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  red using [sqlit
34900 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
34910 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  ded16()]..*/.int
34920 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
34930 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
34940 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
34950 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
34960 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
34970 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
34980 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  ar*).);.int sqli
34990 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
349a0 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
349b0 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
349c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
349d0 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
349e0 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
349f0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  .);../*.** Speci
34a00 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
34a10 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
34a20 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
34a30 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
34a40 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
34a50 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
34a60 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
34a70 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
34a80 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
34a90 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
34aa0 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
34ab0 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
34ac0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
34ad0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
34ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34af0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
34b00 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
34b10 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
34b20 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
34b30 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
34b40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
34b50 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
34b60 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
34b70 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
34b80 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
34b90 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
34ba0 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
34bb0 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
34bc0 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
34bd0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
34be0 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
34bf0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
34c00 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
34c10 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
34c20 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
34c30 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
34c40 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
34c50 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
34c60 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
34c70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34c80 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
34c90 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
34ca0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
34cb0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
34cc0 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
34cd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34ce0 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63  EF: Suspend Exec
34cf0 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72  ution For A Shor
34d00 74 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d 20  t Time {H10530} 
34d10 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S40410>.**.** T
34d20 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  he sqlite3_sleep
34d30 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  () function caus
34d40 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
34d50 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
34d60 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f   execution.** fo
34d70 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d  r at least a num
34d80 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
34d90 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e  nds specified in
34da0 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a   its parameter..
34db0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65  **.** If the ope
34dc0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f  rating system do
34dd0 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73  es not support s
34de0 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69  leep requests wi
34df0 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e  th.** millisecon
34e00 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f  d time resolutio
34e10 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65  n, then the time
34e20 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64   will be rounded
34e30 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65   up to.** the ne
34e40 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68  arest second. Th
34e50 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
34e60 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
34e70 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65  p actually.** re
34e80 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
34e90 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
34ea0 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
34eb0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c  *.** SQLite impl
34ec0 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65  ements this inte
34ed0 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67  rface by calling
34ee0 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a   the xSleep().**
34ef0 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
34f00 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
34f10 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  vfs] object..**.
34f20 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
34f30 2a 0a 2a 2a 20 7b 48 31 30 35 33 33 7d 20 54 68  *.** {H10533} Th
34f40 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  e [sqlite3_sleep
34f50 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69  (M)] interface i
34f60 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 65  nvokes the xSlee
34f70 70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65  p.**          me
34f80 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
34f90 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
34fa0 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74  |VFS] in order t
34fb0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75  o.**          su
34fc0 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 20  spend execution 
34fd0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  of the current t
34fe0 68 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65 61  hread for at lea
34ff0 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d  st.**          M
35000 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a   milliseconds..*
35010 2a 0a 2a 2a 20 7b 48 31 30 35 33 36 7d 20 54 68  *.** {H10536} Th
35020 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  e [sqlite3_sleep
35030 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (M)] interface r
35040 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
35050 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r of.**         
35060 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
35070 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20   sleep actually 
35080 72 65 71 75 65 73 74 65 64 20 6f 66 20 74 68 65  requested of the
35090 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20   operating.**   
350a0 20 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20 77         system, w
350b0 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c 61  hich might be la
350c0 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 70 61  rger than the pa
350d0 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e  rameter M..*/.in
350e0 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  t sqlite3_sleep(
350f0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
35100 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54  I3REF: Name Of T
35110 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e  he Folder Holdin
35120 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65  g Temporary File
35130 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30 30  s {H10310} <S200
35140 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69  00>.**.** If thi
35150 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
35160 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
35170 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  nt to a string w
35180 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e  hich is.** the n
35190 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20  ame of a folder 
351a0 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72  (a.k.a. director
351b0 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d  y), then all tem
351c0 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20  porary files.** 
351d0 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74  created by SQLit
351e0 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  e will be placed
351f0 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
35200 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 72  ry.  If this var
35210 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55  iable.** is a NU
35220 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
35230 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73   SQLite performs
35240 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e   a search for an
35250 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   appropriate.** 
35260 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64  temporary file d
35270 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
35280 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
35290 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  o modify this va
352a0 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 5b 64  riable once a [d
352b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
352c0 6f 6e 5d 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20  on].** has been 
352d0 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73 20 69  opened.  It is i
352e0 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
352f0 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
35300 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
35310 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
35320 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
35330 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
35340 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
35350 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
35360 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69  n call and remai
35370 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68 65 72  n unchanged ther
35380 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54  eafter..*/.SQLIT
35390 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
353a0 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
353b0 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
353c0 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72  PI3REF: Test For
353d0 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64   Auto-Commit Mod
353e0 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 36 30 32  e {H12930} <S602
353f0 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
35400 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   {autocommit mod
35410 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e}.**.** The sql
35420 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
35430 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
35440 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
35450 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
35460 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
35470 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
35480 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
35490 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
354a0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
354b0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
354c0 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  is on by default
354d0 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20  ..** Autocommit 
354e0 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
354f0 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
35500 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f  atement..** Auto
35510 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72  commit mode is r
35520 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b  e-enabled by a [
35530 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c  COMMIT] or [ROLL
35540 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  BACK]..**.** If 
35550 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66  certain kinds of
35560 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e   errors occur on
35570 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74   a statement wit
35580 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74  hin a multi-stat
35590 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63  ement.** transac
355a0 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63  tion (errors inc
355b0 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  luding [SQLITE_F
355c0 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f  ULL], [SQLITE_IO
355d0 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ERR],.** [SQLITE
355e0 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45  _NOMEM], [SQLITE
355f0 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c  _BUSY], and [SQL
35600 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20  ITE_INTERRUPT]) 
35610 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e  then the.** tran
35620 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  saction might be
35630 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
35640 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
35650 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20   only way to.** 
35660 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72  find out whether
35670 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
35680 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
35690 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
356a0 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72  n after.** an er
356b0 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68  ror is to use th
356c0 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
356d0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
356e0 2a 0a 2a 2a 20 7b 48 31 32 39 33 31 7d 20 54 68  *.** {H12931} Th
356f0 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  e [sqlite3_get_a
35700 75 74 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69 6e  utocommit(D)] in
35710 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35720 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20  non-zero or.**  
35730 20 20 20 20 20 20 20 20 7a 65 72 6f 20 69 66 20          zero if 
35740 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
35750 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73 20 6f  nnection] D is o
35760 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f  r is not in auto
35770 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20  commit.**       
35780 20 20 20 6d 6f 64 65 2c 20 72 65 73 70 65 63 74     mode, respect
35790 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ively..**.** {H1
357a0 32 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69 74  2932} Autocommit
357b0 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64   mode is on by d
357c0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  efault..**.** {H
357d0 31 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d 69  12933} Autocommi
357e0 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
357f0 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73 66  ed by a successf
35800 75 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65  ul [BEGIN] state
35810 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ment..**.** {H12
35820 39 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20  934} Autocommit 
35830 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
35840 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c 20  by a successful 
35850 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
35860 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20 20  LBACK].**       
35870 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a     statement..**
35880 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
35890 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 39 33 36 7d 20  .**.** {A12936} 
358a0 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
358b0 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75  d changes the au
358c0 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20  tocommit status 
358d0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
358e0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e  **          conn
358f0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
35900 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
35910 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
35920 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 20  eturn value.**  
35930 20 20 20 20 20 20 20 20 69 73 20 75 6e 64 65 66          is undef
35940 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
35950 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
35960 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
35970 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35980 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
35990 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72  e Handle Of A Pr
359a0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
359b0 20 7b 48 31 33 31 32 30 7d 20 3c 53 36 30 36 30   {H13120} <S6060
359c0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
359d0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
359e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
359f0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
35a00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
35a10 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20  e.** to which a 
35a20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
35a30 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 54  ent] belongs.  T
35a40 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  he database hand
35a50 6c 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  le returned by.*
35a60 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  * sqlite3_db_han
35a70 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  dle is the same 
35a80 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
35a90 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72  that was the fir
35aa0 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  st argument.** t
35ab0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  o the [sqlite3_p
35ac0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c  repare_v2()] cal
35ad0 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e  l (or its varian
35ae0 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65  ts) that was use
35af0 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74  d to.** create t
35b00 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  he statement in 
35b10 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
35b20 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
35b30 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 32 33  S:.**.** {H13123
35b40 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  } The [sqlite3_d
35b50 62 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74  b_handle(S)] int
35b60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
35b70 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20   pointer.**     
35b80 20 20 20 20 20 74 6f 20 74 68 65 20 5b 64 61 74       to the [dat
35b90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35ba0 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  ] associated wit
35bb0 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  h the.**        
35bc0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
35bd0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c  ement] S..*/.sql
35be0 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62  ite3 *sqlite3_db
35bf0 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
35c00 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
35c10 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68  API3REF: Find th
35c20 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20  e next prepared 
35c30 73 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 34  statement {H1314
35c40 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a  0} <S60600>.**.*
35c50 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
35c60 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
35c70 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b  er to the next [
35c80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35c90 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74  nt] after.** pSt
35ca0 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  mt associated wi
35cb0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
35cc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62   connection] pDb
35cd0 2e 20 20 49 66 20 70 53 74 6d 74 20 69 73 20 4e  .  If pStmt is N
35ce0 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ULL.** then this
35cf0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
35d00 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
35d10 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72  the first prepar
35d20 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
35d30 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
35d40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
35d50 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 49 66  nection pDb.  If
35d60 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61   no prepared sta
35d70 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66  tement.** satisf
35d80 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f  ies the conditio
35d90 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  ns of this routi
35da0 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e  ne, it returns N
35db0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ULL..**.** INVAR
35dc0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
35dd0 33 31 34 33 7d 20 49 66 20 44 20 69 73 20 61 20  3143} If D is a 
35de0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35df0 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73  tion] that holds
35e00 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
35e10 20 20 20 20 20 20 20 20 20 75 6e 66 69 6e 61 6c           unfinal
35e20 69 7a 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  ized [prepared s
35e30 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53  tatements] and S
35e40 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
35e50 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  er,.**          
35e60 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65  then [sqlite3_ne
35e70 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72  xt_stmt(D, S)] r
35e80 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74  outine shall ret
35e90 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  urn a pointer.**
35ea0 20 20 20 20 20 20 20 20 20 20 74 6f 20 6f 6e 65            to one
35eb0 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64   of the prepared
35ec0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
35ed0 63 69 61 74 65 64 20 77 69 74 68 20 44 2e 0a 2a  ciated with D..*
35ee0 2a 0a 2a 2a 20 7b 48 31 33 31 34 36 7d 20 49 66  *.** {H13146} If
35ef0 20 44 20 69 73 20 61 20 5b 64 61 74 61 62 61 73   D is a [databas
35f00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
35f10 61 74 20 68 6f 6c 64 73 20 6e 6f 20 75 6e 66 69  at holds no unfi
35f20 6e 61 6c 69 7a 65 64 0a 2a 2a 20 20 20 20 20 20  nalized.**      
35f30 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
35f40 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20  atements] and S 
35f50 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
35f60 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  r, then.**      
35f70 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78      [sqlite3_nex
35f80 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f  t_stmt(D, S)] ro
35f90 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75  utine shall retu
35fa0 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  rn a NULL pointe
35fb0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 39  r..**.** {H13149
35fc0 7d 20 49 66 20 53 20 69 73 20 61 20 5b 70 72 65  } If S is a [pre
35fd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
35fe0 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   in the [databas
35ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
36000 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
36010 53 20 69 73 20 6e 6f 74 20 74 68 65 20 6c 61 73  S is not the las
36020 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
36030 6d 65 6e 74 20 69 6e 20 44 2c 20 74 68 65 6e 0a  ment in D, then.
36040 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
36050 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44  ite3_next_stmt(D
36060 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  , S)] routine sh
36070 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 6f 69  all return a poi
36080 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  nter.**         
36090 20 74 6f 20 74 68 65 20 6e 65 78 74 20 70 72 65   to the next pre
360a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
360b0 69 6e 20 44 20 61 66 74 65 72 20 53 2e 0a 2a 2a  in D after S..**
360c0 0a 2a 2a 20 7b 48 31 33 31 35 32 7d 20 49 66 20  .** {H13152} If 
360d0 53 20 69 73 20 74 68 65 20 6c 61 73 74 20 5b 70  S is the last [p
360e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
360f0 74 5d 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  t] in the.**    
36100 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
36110 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 68  connection] D th
36120 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
36130 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d  next_stmt(D, S)]
36140 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75  .**          rou
36150 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72  tine shall retur
36160 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
36170 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
36180 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 31  ONS:.**.** {A131
36190 35 34 7d 20 54 68 65 20 5b 64 61 74 61 62 61 73  54} The [databas
361a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po
361b0 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c  inter D in a cal
361c0 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  l to.**         
361d0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
361e0 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72  tmt(D,S)] must r
361f0 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20  efer to an open 
36200 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20  database.**     
36210 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20       connection 
36220 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
36230 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
36240 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
36250 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73  .sqlite3_stmt *s
36260 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
36270 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73  (sqlite3 *pDb, s
36280 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
36290 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
362a0 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64  3REF: Commit And
362b0 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69   Rollback Notifi
362c0 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
362d0 20 7b 48 31 32 39 35 30 7d 20 3c 53 36 30 34 30   {H12950} <S6040
362e0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
362f0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
36300 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
36310 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
36320 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
36330 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
36340 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
36350 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e  on is committed.
36360 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b  .** Any callback
36370 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
36380 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
36390 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
363a0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
363b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
363c0 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
363d0 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  en..** The sqlit
363e0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
363f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
36400 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
36410 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
36420 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
36430 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
36440 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e  on is committed.
36450 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b  .** Any callback
36460 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
36470 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
36480 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
36490 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
364a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
364b0 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
364c0 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 20  en..** The pArg 
364d0 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73  argument is pass
364e0 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
364f0 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49  e callback..** I
36500 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f  f the callback o
36510 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  n a commit hook 
36520 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
36530 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68   non-zero,.** th
36540 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
36550 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
36560 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  a rollback..**.*
36570 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e  * If another fun
36580 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f  ction was previo
36590 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c  usly registered,
365a0 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c   its.** pArg val
365b0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
365c0 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20   Otherwise NULL 
365d0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
365e0 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20 61  ** Registering a
365f0 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64   NULL function d
36600 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c  isables the call
36610 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  back..**.** For 
36620 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
36630 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e  this API, a tran
36640 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20  saction is said 
36650 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20  to have been.** 
36660 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61  rolled back if a
36670 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c  n explicit "ROLL
36680 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20  BACK" statement 
36690 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a  is executed, or.
366a0 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63  ** an error or c
366b0 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73  onstraint causes
366c0 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c   an implicit rol
366d0 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a  lback to occur..
366e0 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  ** The rollback 
366f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
36700 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
36710 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61  nsaction is.** a
36720 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
36730 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65  led back because
36740 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
36750 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
36760 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62  ed..** The rollb
36770 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
36780 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
36790 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
367a0 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ** rolled back b
367b0 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20  ecause a commit 
367c0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65  callback returne
367d0 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c  d non-zero..** <
367e0 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74  todo> Check on t
367f0 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  his </todo>.**.*
36800 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
36810 0a 2a 2a 20 7b 48 31 32 39 35 31 7d 20 54 68 65  .** {H12951} The
36820 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   [sqlite3_commit
36830 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e  _hook(D,F,P)] in
36840 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
36850 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
36860 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74    callback funct
36870 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f  ion F to be invo
36880 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ked with argumen
36890 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  t P whenever.** 
368a0 20 20 20 20 20 20 20 20 20 61 20 74 72 61 6e 73           a trans
368b0 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20 6f  action commits o
368c0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
368d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
368e0 2a 0a 2a 2a 20 7b 48 31 32 39 35 32 7d 20 54 68  *.** {H12952} Th
368f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  e [sqlite3_commi
36900 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  t_hook(D,F,P)] i
36910 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
36920 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 0a   the P argument.
36930 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
36940 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
36950 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ll with the same
36960 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36970 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20  ction] D,.**    
36980 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 6f 6e        or NULL on
36990 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
369a0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
369b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
369c0 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tion D..**.** {H
369d0 31 32 39 35 33 7d 20 45 61 63 68 20 63 61 6c 6c  12953} Each call
369e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
369f0 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72  mit_hook()] over
36a00 77 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62  writes the callb
36a10 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
36a20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 70 72  registered by pr
36a30 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a  ior calls..**.**
36a40 20 7b 48 31 32 39 35 34 7d 20 49 66 20 74 68 65   {H12954} If the
36a50 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b   F argument to [
36a60 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
36a70 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e  ook(D,F,P)] is N
36a80 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
36a90 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  then the commit 
36aa0 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  hook callback is
36ab0 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f   canceled and no
36ac0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
36ad0 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64        is invoked
36ae0 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74   when a transact
36af0 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a  ion commits..**.
36b00 2a 2a 20 7b 48 31 32 39 35 35 7d 20 49 66 20 74  ** {H12955} If t
36b10 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61  he commit callba
36b20 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
36b30 65 72 6f 20 74 68 65 6e 20 74 68 65 20 63 6f 6d  ero then the com
36b40 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  mit is.**       
36b50 20 20 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74     converted int
36b60 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  o a rollback..**
36b70 0a 2a 2a 20 7b 48 31 32 39 36 31 7d 20 54 68 65  .** {H12961} The
36b80 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
36b90 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  ck_hook(D,F,P)] 
36ba0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
36bb0 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ers the.**      
36bc0 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e      callback fun
36bd0 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e  ction F to be in
36be0 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
36bf0 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
36c00 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61  *          a tra
36c10 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62  nsaction rolls b
36c20 61 63 6b 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  ack on the [data
36c30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36c40 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36   D..**.** {H1296
36c50 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
36c60 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c  rollback_hook(D,
36c70 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
36c80 72 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a  returns the P.**
36c90 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65            argume
36ca0 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76  nt from the prev
36cb0 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74  ious call with t
36cc0 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
36cd0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
36ce0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
36cf0 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73  NULL on the firs
36d00 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  t call.**       
36d10 20 20 20 66 6f 72 20 61 20 70 61 72 74 69 63 75     for a particu
36d20 6c 61 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  lar database con
36d30 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  nection D..**.**
36d40 20 7b 48 31 32 39 36 33 7d 20 45 61 63 68 20 63   {H12963} Each c
36d50 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
36d60 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d  rollback_hook()]
36d70 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20   overwrites the 
36d80 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
36d90 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
36da0 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a  by prior calls..
36db0 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 34 7d 20 49  **.** {H12964} I
36dc0 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74  f the F argument
36dd0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c   to [sqlite3_rol
36de0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50  lback_hook(D,F,P
36df0 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20  )] is NULL.**   
36e00 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
36e10 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61  rollback hook ca
36e20 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c  llback is cancel
36e30 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61  ed and no callba
36e40 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ck.**          i
36e50 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
36e60 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c   transaction rol
36e70 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 64  ls back..*/.void
36e80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   *sqlite3_commit
36e90 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
36ea0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
36eb0 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  oid*);.void *sql
36ec0 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
36ed0 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ok(sqlite3*, voi
36ee0 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f  d(*)(void *), vo
36ef0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
36f00 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e  I3REF: Data Chan
36f10 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ge Notification 
36f20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 37  Callbacks {H1297
36f30 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a  0} <S60400>.**.*
36f40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70  * The sqlite3_up
36f50 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  date_hook() inte
36f60 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
36f70 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
36f80 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
36f90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36fa0 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64  tion] identified
36fb0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
36fc0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  gument.** to be 
36fd0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
36fe0 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65   a row is update
36ff0 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
37000 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63  eleted..** Any c
37010 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
37020 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
37030 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  o this function.
37040 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
37050 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37060 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
37070 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  n..**.** The sec
37080 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
37090 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
370a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76   function to inv
370b0 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f  oke when a.** ro
370c0 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
370d0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
370e0 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  d..** The first 
370f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
37100 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
37110 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20  py of the third 
37120 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
37130 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
37140 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  ok()..** The sec
37150 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67  ond callback arg
37160 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
37170 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
37180 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
37190 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
371a0 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69  UPDATE], dependi
371b0 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ng on the operat
371c0 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
371d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
371e0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  to be invoked..*
371f0 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20  * The third and 
37200 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
37210 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
37220 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
37230 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
37240 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
37250 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
37260 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
37270 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61  .** The final ca
37280 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72  llback parameter
37290 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66   is the rowid of
372a0 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 74 68 65   the row. In the
372b0 20 63 61 73 65 20 6f 66 0a 2a 2a 20 61 6e 20 75   case of.** an u
372c0 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74  pdate, this is t
372d0 68 65 20 72 6f 77 69 64 20 61 66 74 65 72 20 74  he rowid after t
372e0 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20  he update takes 
372f0 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  place..**.** The
37300 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20   update hook is 
37310 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
37320 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
37330 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d   tables are.** m
37340 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71  odified (i.e. sq
37350 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
37360 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29  sqlite_sequence)
37370 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
37380 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  er function was 
37390 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
373a0 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 20  tered, its pArg 
373b0 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75  value.** is retu
373c0 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
373d0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
373e0 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
373f0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  NTS:.**.** {H129
37400 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  71} The [sqlite3
37410 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46  _update_hook(D,F
37420 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,P)] interface c
37430 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
37440 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ck.**          f
37450 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20  unction F to be 
37460 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 69 72  invoked with fir
37470 73 74 20 70 61 72 61 6d 65 74 65 72 20 50 20 77  st parameter P w
37480 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20  henever.**      
37490 20 20 20 20 61 20 74 61 62 6c 65 20 72 6f 77 20      a table row 
374a0 69 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73  is modified, ins
374b0 65 72 74 65 64 2c 20 6f 72 20 64 65 6c 65 74 65  erted, or delete
374c0 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  d on.**         
374d0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
374e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
374f0 0a 2a 2a 20 7b 48 31 32 39 37 33 7d 20 54 68 65  .** {H12973} The
37500 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
37510 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e  _hook(D,F,P)] in
37520 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37530 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  the value.**    
37540 20 20 20 20 20 20 6f 66 20 50 20 66 6f 72 20 74        of P for t
37550 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
37560 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
37570 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37580 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20  n] D,.**        
37590 20 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68    or NULL for th
375a0 65 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a 2a  e first call..**
375b0 0a 2a 2a 20 7b 48 31 32 39 37 35 7d 20 49 66 20  .** {H12975} If 
375c0 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  the update hook 
375d0 63 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73  callback F in [s
375e0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
375f0 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20  ok(D,F,P)].**   
37600 20 20 20 20 20 20 20 69 73 20 4e 55 4c 4c 20 74         is NULL t
37610 68 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61 74  hen the no updat
37620 65 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20  e callbacks are 
37630 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  made..**.** {H12
37640 39 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 20 74  977} Each call t
37650 6f 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  o [sqlite3_updat
37660 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 6f  e_hook(D,F,P)] o
37670 76 65 72 72 69 64 65 73 20 70 72 69 6f 72 20 63  verrides prior c
37680 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  alls.**         
37690 20 74 6f 20 74 68 65 20 73 61 6d 65 20 69 6e 74   to the same int
376a0 65 72 66 61 63 65 20 6f 6e 20 74 68 65 20 73 61  erface on the sa
376b0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
376c0 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
376d0 2a 20 7b 48 31 32 39 37 39 7d 20 54 68 65 20 75  * {H12979} The u
376e0 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62  pdate hook callb
376f0 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
37700 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c  ed when internal
37710 20 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20 20   system.**      
37720 20 20 20 20 74 61 62 6c 65 73 20 73 75 63 68 20      tables such 
37730 61 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72  as sqlite_master
37740 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75   and sqlite_sequ
37750 65 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69 65  ence are modifie
37760 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38 31  d..**.** {H12981
37770 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  } The second par
37780 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 75 70  ameter to the up
37790 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  date callback.**
377a0 20 20 20 20 20 20 20 20 20 20 69 73 20 6f 6e 65            is one
377b0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45   of [SQLITE_INSE
377c0 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c  RT], [SQLITE_DEL
377d0 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ETE] or [SQLITE_
377e0 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20 20  UPDATE],.**     
377f0 20 20 20 20 20 64 65 70 65 6e 64 69 6e 67 20 6f       depending o
37800 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  n the operation 
37810 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20  that caused the 
37820 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69  callback to be i
37830 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nvoked..**.** {H
37840 31 32 39 38 33 7d 20 54 68 65 20 74 68 69 72 64  12983} The third
37850 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75   and fourth argu
37860 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c  ments to the cal
37870 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f  lback contain po
37880 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20  inters.**       
37890 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69     to zero-termi
378a0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
378b0 6e 67 73 20 77 68 69 63 68 20 61 72 65 20 74 68  ngs which are th
378c0 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  e names of the.*
378d0 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
378e0 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 74 68  ase and table th
378f0 61 74 20 69 73 20 62 65 69 6e 67 20 75 70 64 61  at is being upda
37900 74 65 64 2e 0a 0a 2a 2a 20 7b 48 31 32 39 38 35  ted...** {H12985
37910 7d 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c  } The final call
37920 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
37930 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  s the rowid of t
37940 68 65 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a 20  he row after.** 
37950 20 20 20 20 20 20 20 20 20 74 68 65 20 63 68 61           the cha
37960 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76  nge occurs..*/.v
37970 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64  oid *sqlite3_upd
37980 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69  ate_hook(.  sqli
37990 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  te3*, .  void(*)
379a0 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61  (void *,int ,cha
379b0 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63  r const *,char c
379c0 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69  onst *,sqlite3_i
379d0 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29  nt64),.  void*.)
379e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
379f0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
37a00 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65  able Shared Page
37a10 72 20 43 61 63 68 65 20 7b 48 31 30 33 33 30 7d  r Cache {H10330}
37a20 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 45 59   <S30900>.** KEY
37a30 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63  WORDS: {shared c
37a40 61 63 68 65 7d 20 7b 73 68 61 72 65 64 20 63 61  ache} {shared ca
37a50 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  che mode}.**.** 
37a60 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61  This routine ena
37a70 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
37a80 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20   the sharing of 
37a90 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63  the database cac
37aa0 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61  he.** and schema
37ab0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
37ac0 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61   between [databa
37ad0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20  se connection | 
37ae0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20  connections].** 
37af0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
37b00 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73  base. Sharing is
37b10 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
37b20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65  argument is true
37b30 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64  .** and disabled
37b40 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
37b50 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a   is false..**.**
37b60 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69   Cache sharing i
37b70 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69  s enabled and di
37b80 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e  sabled for an en
37b90 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20 7b 45  tire process. {E
37ba0 4e 44 7d 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ND}.** This is a
37bb0 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
37bc0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
37bd0 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
37be0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
37bf0 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
37c00 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
37c10 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
37c20 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
37c30 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20  **.** The cache 
37c40 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
37c50 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
37c60 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
37c70 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
37c80 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
37c90 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
37ca0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
37cb0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
37cc0 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
37cd0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37ce0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
37cf0 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
37d00 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
37d10 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
37d20 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
37d30 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69  opened..**.** Vi
37d40 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e  rtual tables can
37d50 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74 68  not be used with
37d60 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65 2e   a shared cache.
37d70 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a    When shared.**
37d80 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
37d90 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d, the [sqlite3_
37da0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
37db0 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67   API used to reg
37dc0 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c  ister.** virtual
37dd0 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77   tables will alw
37de0 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72  ays return an er
37df0 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ror..**.** This 
37e00 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
37e10 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73  [SQLITE_OK] if s
37e20 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20  hared cache was 
37e30 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
37e40 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  led.** successfu
37e50 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20  lly.  An [error 
37e60 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
37e70 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  d otherwise..**.
37e80 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65 20  ** Shared cache 
37e90 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
37ea0 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73  efault. But this
37eb0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
37ec0 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61  .** future relea
37ed0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ses of SQLite.  
37ee0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
37ef0 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61  t care about sha
37f00 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74  red.** cache set
37f10 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20  ting should set 
37f20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a  it explicitly..*
37f30 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
37f40 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 31 7d 20  .**.** {H10331} 
37f50 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
37f60 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
37f70 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
37f80 64 5f 63 61 63 68 65 28 42 29 5d 0a 2a 2a 20 20  d_cache(B)].**  
37f90 20 20 20 20 20 20 20 20 77 69 6c 6c 20 65 6e 61          will ena
37fa0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 73  ble or disable s
37fb0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
37fc0 20 66 6f 72 20 61 6e 79 20 73 75 62 73 65 71 75   for any subsequ
37fd0 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ently.**        
37fe0 20 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 62    created [datab
37ff0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
38000 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63  in the same proc
38010 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33  ess..**.** {H103
38020 33 36 7d 20 57 68 65 6e 20 73 68 61 72 65 64 20  36} When shared 
38030 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
38040 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  , the [sqlite3_c
38050 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 0a  reate_module()].
38060 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
38070 72 66 61 63 65 20 77 69 6c 6c 20 61 6c 77 61 79  rface will alway
38080 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  s return an erro
38090 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 37  r..**.** {H10337
380a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
380b0 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
380c0 68 65 28 42 29 5d 20 69 6e 74 65 72 66 61 63 65  he(B)] interface
380d0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
380e0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
380f0 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
38100 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
38110 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 73 73  disabled success
38120 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fully..**.** {H1
38130 30 33 33 39 7d 20 53 68 61 72 65 64 20 63 61 63  0339} Shared cac
38140 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  he is disabled b
38150 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e  y default..*/.in
38160 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  t sqlite3_enable
38170 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e  _shared_cache(in
38180 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
38190 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20  REF: Attempt To 
381a0 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79  Free Heap Memory
381b0 20 7b 48 31 37 33 34 30 7d 20 3c 53 33 30 32 32   {H17340} <S3022
381c0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
381d0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
381e0 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  ory() interface 
381f0 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65  attempts to free
38200 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68   N bytes.** of h
38210 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65  eap memory by de
38220 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65  allocating non-e
38230 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20  ssential memory 
38240 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68  allocations.** h
38250 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62  eld by the datab
38260 61 73 65 20 6c 69 62 72 61 72 79 2e 20 7b 45 4e  ase library. {EN
38270 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20  D}  Memory used 
38280 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73  to cache databas
38290 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d  e.** pages to im
382a0 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
382b0 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  e is an example 
382c0 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  of non-essential
382d0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73 71 6c 69   memory..** sqli
382e0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
382f0 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 65  ry() returns the
38300 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
38310 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c   actually freed,
38320 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20  .** which might 
38330 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20  be more or less 
38340 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  than the amount 
38350 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a  requested..**.**
38360 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
38370 2a 2a 20 7b 48 31 37 33 34 31 7d 20 54 68 65 20  ** {H17341} The 
38380 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
38390 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 69 6e 74 65  _memory(N)] inte
383a0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
383b0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  o.**          fr
383c0 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65  ee N bytes of he
383d0 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61  ap memory by dea
383e0 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73  llocating non-es
383f0 73 65 6e 74 69 61 6c 0a 2a 2a 20 20 20 20 20 20  sential.**      
38400 20 20 20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63      memory alloc
38410 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74  ations held by t
38420 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72  he database libr
38430 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 33  ary..**.** {H163
38440 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  42} The [sqlite3
38450 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
38460 4e 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20  N)] returns the 
38470 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20  number.**       
38480 20 20 20 6f 66 20 62 79 74 65 73 20 61 63 74 75     of bytes actu
38490 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 69 63  ally freed, whic
384a0 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20  h might be more 
384b0 6f 72 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20  or less.**      
384c0 20 20 20 20 74 68 61 6e 20 74 68 65 20 61 6d 6f      than the amo
384d0 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
384e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
384f0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74  lease_memory(int
38500 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38510 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d  EF: Impose A Lim
38520 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20  it On Heap Size 
38530 7b 48 31 37 33 35 30 7d 20 3c 53 33 30 32 32 30  {H17350} <S30220
38540 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
38550 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
38560 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
38570 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20  places a "soft" 
38580 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  limit.** on the 
38590 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
385a0 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
385b0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
385c0 51 4c 69 74 65 2e 0a 2a 2a 20 49 66 20 61 6e 20  QLite..** If an 
385d0 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74  internal allocat
385e0 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
385f0 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65   that would exce
38600 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68  ed the.** soft h
38610 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69  eap limit, [sqli
38620 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
38630 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  ry()] is invoked
38640 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   one or.** more 
38650 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70  times to free up
38660 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f   some space befo
38670 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f  re the allocatio
38680 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a  n is performed..
38690 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20  **.** The limit 
386a0 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22  is called "soft"
386b0 2c 20 62 65 63 61 75 73 65 20 69 66 20 5b 73 71  , because if [sq
386c0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
386d0 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f  mory()].** canno
386e0 74 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e  t free sufficien
386f0 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76  t memory to prev
38700 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72  ent the limit fr
38710 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65  om being exceede
38720 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  d,.** the memory
38730 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e   is allocated an
38740 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72  yway and the cur
38750 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70  rent operation p
38760 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41  roceeds..**.** A
38770 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72   negative or zer
38780 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65  o value for N me
38790 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69  ans that there i
387a0 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c  s no soft heap l
387b0 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  imit and.** [sql
387c0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
387d0 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79  ory()] will only
387e0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
387f0 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73  memory is exhaus
38800 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61  ted..** The defa
38810 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ult value for th
38820 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
38830 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t is zero..**.**
38840 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
38850 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68  best effort to h
38860 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65  onor the soft he
38870 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 74  ap limit..** But
38880 20 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 61   if the soft hea
38890 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62  p limit ca