/ Hex Artifact Content
Login

Artifact 534688abf1580de0a458f017c97770a96c3827ac:


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 38 31 20 32 30 30 38 2f 30  n,v 1.381 2008/0
05f0: 37 2f 32 38 20 30 35 3a 32 32 3a 33 36 20 64 61  7/28 05:22:36 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 61 72 67  takes single arg
bff0: 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
c000: 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
c010: 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
c020: 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
c030: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
c040: 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
c050: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
c060: 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 57  ** statistics. W
c070: 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74 68  hen disabled, th
c080: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  e following SQLi
c090: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
c0a0: 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65  come .** non-ope
c0b0: 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
c0c0: 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
c0d0: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
c0e0: 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
c0f0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
c100: 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
c110: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
c120: 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
c130: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 73 71 6c  )].**   <li> sql
c140: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 73 74 61 74  ite3_memory_stat
c150: 75 73 28 29 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a  us().**   </ul>.
c160: 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
c170: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
c180: 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
c190: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
c1a0: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
c1b0: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
c1c0: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
c1d0: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72  n use for.** scr
c1e0: 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68  atch memory.  Th
c1f0: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
c200: 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e  guments:  A poin
c210: 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
c220: 79 2c 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  y, the.** size o
c230: 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 62  f each scratch b
c240: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
c250: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 75  the number of bu
c260: 66 66 65 72 73 20 28 4e 29 2e 20 20 54 68 65 20  ffers (N).  The 
c270: 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  sz.** argument m
c280: 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c  ust be a multipl
c290: 65 20 6f 66 20 31 36 2e 20 54 68 65 20 66 69 72  e of 16. The fir
c2a0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  st.** argument s
c2b0: 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61  hould point to a
c2c0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20  n allocation of 
c2d0: 61 74 20 6c 65 61 73 74 20 28 73 7a 2b 34 29 2a  at least (sz+4)*
c2e0: 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
c2f0: 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  y..** SQLite wil
c300: 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68  l use no more th
c310: 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62  an one scratch b
c320: 75 66 66 65 72 20 61 74 20 6f 6e 63 65 20 70 65  uffer at once pe
c330: 72 20 74 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20  r thread, so.** 
c340: 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
c350: 74 6f 20 74 68 65 20 65 78 70 65 63 74 65 64 20  to the expected 
c360: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
c370: 66 20 74 68 72 65 61 64 73 2e 20 20 54 68 65 20  f threads.  The 
c380: 73 7a 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  sz.** parameter 
c390: 73 68 6f 75 6c 64 20 62 65 20 36 20 74 69 6d 65  should be 6 time
c3a0: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
c3b0: 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
c3c0: 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a  se page size..**
c3d0: 20 53 63 72 61 74 63 68 20 62 75 66 66 65 72 73   Scratch buffers
c3e0: 20 61 72 65 20 75 73 65 64 20 61 73 20 70 61 72   are used as par
c3f0: 74 20 6f 66 20 74 68 65 20 62 74 72 65 65 20 62  t of the btree b
c400: 61 6c 61 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e  alance operation
c410: 2e 20 20 49 66 0a 2a 2a 20 54 68 65 20 62 74 72  .  If.** The btr
c420: 65 65 20 62 61 6c 61 6e 63 65 72 20 6e 65 65 64  ee balancer need
c430: 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d  s additional mem
c440: 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
c450: 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 0a 2a  is provided by.*
c460: 2a 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  * scratch buffer
c470: 73 20 6f 72 20 69 66 20 6e 6f 20 73 63 72 61 74  s or if no scrat
c480: 63 68 20 62 75 66 66 65 72 20 73 70 61 63 65 20  ch buffer space 
c490: 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
c4a0: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65  en SQLite.** goe
c4b0: 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
c4c0: 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f 62 74 61 69  lloc()] to obtai
c4d0: 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 74 20  n the memory it 
c4e0: 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  needs.</dd>.**.*
c4f0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
c500: 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
c510: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
c520: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
c530: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
c540: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
c550: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
c560: 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  * the database p
c570: 61 67 65 20 63 61 63 68 65 2e 20 20 54 68 65 72  age cache.  Ther
c580: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
c590: 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65 72  ments: A pointer
c5a0: 20 74 6f 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72   to the.** memor
c5b0: 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  y, the size of e
c5c0: 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20  ach page buffer 
c5d0: 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75  (sz), and the nu
c5e0: 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e  mber of pages (N
c5f0: 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
c600: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
c610: 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
c620: 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37  ween 512 and 327
c630: 36 38 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  68.  The first.*
c640: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
c650: 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
c660: 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
c670: 65 61 73 74 20 28 73 7a 2b 34 29 2a 4e 20 62 79  east (sz+4)*N by
c680: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
c690: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  * SQLite will us
c6a0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
c6b0: 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72  vided by the fir
c6c0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
c6d0: 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65  atisfy its.** me
c6e0: 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74  mory needs for t
c6f0: 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73  he first N pages
c700: 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f   that it adds to
c710: 20 63 61 63 68 65 2e 20 20 49 66 20 61 64 64 69   cache.  If addi
c720: 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
c730: 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
c740: 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
c750: 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
c760: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68   this option, th
c770: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65  en.** SQLite goe
c780: 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
c790: 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20  lloc()] for the 
c7a0: 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61  additional stora
c7b0: 67 65 20 73 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a  ge space.</dd>.*
c7c0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
c7d0: 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
c7e0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c7f0: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
c800: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
c810: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
c820: 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72   will use.** for
c830: 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
c840: 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
c850: 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f  ation needs beyo
c860: 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65  nd those provide
c870: 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c  d.** for by [SQL
c880: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
c890: 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  CH] and [SQLITE_
c8a0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
c8b0: 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  ]..** There are 
c8c0: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
c8d0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
c8e0: 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 6e 75  e memory, the nu
c8f0: 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
c900: 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
c910: 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
c920: 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
c930: 6e 20 73 69 7a 65 2e 20 20 49 66 0a 2a 2a 20 74  n size.  If.** t
c940: 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
c950: 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
c960: 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
c970: 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
c980: 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
c990: 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
c9a0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
c9b0: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
c9c0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
c9d0: 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
c9e0: 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
c9f0: 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
ca00: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66  FIG_MALLOC].  If
ca10: 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
ca20: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
ca30: 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
ca40: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
ca50: 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
ca60: 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
ca70: 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
ca80: 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
ca90: 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
caa0: 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
cab0: 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
cac0: 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
cad0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
cae0: 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  needs.</dd>.**.*
caf0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
cb00: 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
cb10: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
cb20: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
cb30: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
cb40: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
cb50: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
cb60: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
cb70: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
cb80: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
cb90: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
cba0: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
cbb0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
cbc0: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
cbd0: 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
cbe0: 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
cbf0: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
cc00: 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Lite.</dd>.**.**
cc10: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
cc20: 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
cc30: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
cc40: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
cc50: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
cc60: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
cc70: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
cc80: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
cc90: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
cca0: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
ccb0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
ccc0: 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
ccd0: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
cce0: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
ccf0: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
cd00: 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  ex routines..** 
cd10: 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
cd20: 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
cd30: 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
cd40: 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
cd50: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
cd60: 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
cd70: 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
cd80: 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
cd90: 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
cda0: 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
cdb0: 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e  or example.</dd>
cdc0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
cdd0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
cde0: 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69  THREAD  1  /* ni
cdf0: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
ce00: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
ce10: 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e  THREAD   2  /* n
ce20: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
ce30: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
ce40: 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20  ALIZED    3  /* 
ce50: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
ce60: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
ce70: 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a  LOC        4  /*
ce80: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
ce90: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
cea0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
ceb0: 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20  ETMALLOC     5  
cec0: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
ced0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
cee0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
cef0: 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36  _SCRATCH       6
cf00: 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
cf10: 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
cf20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
cf30: 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
cf40: 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
cf50: 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
cf60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
cf70: 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
cf80: 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
cf90: 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
cfa0: 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
cfb0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
cfc0: 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
cfd0: 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
cfe0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
cff0: 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
d000: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
d010: 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
d020: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
d030: 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
d040: 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
d050: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
d060: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d070: 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c  E_CONFIG_CHUNKAL
d080: 4c 4f 43 20 20 20 31 32 20 20 2f 2a 20 69 6e 74  LOC   12  /* int
d090: 20 74 68 72 65 73 68 6f 6c 64 20 2a 2f 0a 0a 0a   threshold */...
d0a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d0b0: 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
d0c0: 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
d0d0: 74 20 43 6f 64 65 73 20 7b 48 31 32 32 30 30 7d  t Codes {H12200}
d0e0: 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10700>.**.** 
d0f0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
d100: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
d110: 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
d120: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
d130: 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
d140: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
d150: 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
d160: 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72  . The extended r
d170: 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
d180: 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
d190: 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
d1a0: 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
d1b0: 69 74 79 20 63 6f 6e 73 69 64 65 72 61 74 69 6f  ity consideratio
d1c0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ns..**.** INVARI
d1d0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
d1e0: 32 30 31 7d 20 45 61 63 68 20 6e 65 77 20 5b 64  201} Each new [d
d1f0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d200: 6f 6e 5d 20 73 68 61 6c 6c 20 68 61 76 65 20 74  on] shall have t
d210: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
d220: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
d230: 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 64  codes] feature d
d240: 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
d250: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30  lt..**.** {H1220
d260: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
d270: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
d280: 63 6f 64 65 73 28 44 2c 46 29 5d 20 69 6e 74 65  codes(D,F)] inte
d290: 72 66 61 63 65 20 73 68 61 6c 6c 20 65 6e 61 62  rface shall enab
d2a0: 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  le.**          [
d2b0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
d2c0: 63 6f 64 65 73 5d 20 66 6f 72 20 74 68 65 20 20  codes] for the  
d2d0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
d2e0: 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20  tion] D.**      
d2f0: 20 20 20 20 69 66 20 74 68 65 20 46 20 70 61 72      if the F par
d300: 61 6d 65 74 65 72 20 69 73 20 74 72 75 65 2c 20  ameter is true, 
d310: 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 6d 20  or disable them 
d320: 69 66 20 46 20 69 73 20 66 61 6c 73 65 2e 0a 2a  if F is false..*
d330: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
d340: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
d350: 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
d360: 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
d370: 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
d380: 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b 48 31  Insert Rowid {H1
d390: 32 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  2220} <S10700>.*
d3a0: 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20  *.** Each entry 
d3b0: 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
d3c0: 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
d3d0: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
d3e0: 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
d3f0: 6c 65 64 20 74 68 65 20 22 72 6f 77 69 64 22 2e  led the "rowid".
d400: 20 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c   The rowid is al
d410: 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
d420: 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
d430: 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
d440: 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
d450: 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
d460: 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
d470: 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
d480: 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
d490: 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
d4a0: 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  s. If.** the tab
d4b0: 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
d4c0: 6f 66 20 74 79 70 65 20 49 4e 54 45 47 45 52 20  of type INTEGER 
d4d0: 50 52 49 4d 41 52 59 20 4b 45 59 20 74 68 65 6e  PRIMARY KEY then
d4e0: 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
d4f0: 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
d500: 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
d510: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
d520: 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 72  ne returns the r
d530: 6f 77 69 64 20 6f 66 20 74 68 65 20 6d 6f 73 74  owid of the most
d540: 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
d550: 73 73 66 75 6c 20 49 4e 53 45 52 54 20 69 6e 74  ssful INSERT int
d560: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
d570: 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
d580: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
d590: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
d5a0: 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73  gument.  If no s
d5b0: 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54  uccessful INSERT
d5c0: 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
d5d0: 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20  ccurred on that 
d5e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d5f0: 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74  ion, zero is ret
d600: 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  urned..**.** If 
d610: 61 6e 20 49 4e 53 45 52 54 20 6f 63 63 75 72 73  an INSERT occurs
d620: 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
d630: 72 2c 20 74 68 65 6e 20 74 68 65 20 72 6f 77 69  r, then the rowi
d640: 64 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  d of the inserte
d650: 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75  d.** row is retu
d660: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
d670: 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20  tine as long as 
d680: 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72  the trigger is r
d690: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
d6a0: 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
d6b0: 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20  terminates, the 
d6c0: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
d6d0: 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  y this routine.*
d6e0: 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65  * reverts to the
d6f0: 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65   last value inse
d700: 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  rted before the 
d710: 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a  trigger fired..*
d720: 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45 52 54 20 74  *.** An INSERT t
d730: 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
d740: 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
d750: 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
d760: 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 49  .** successful I
d770: 4e 53 45 52 54 20 61 6e 64 20 64 6f 65 73 20 6e  NSERT and does n
d780: 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
d790: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
d7a0: 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
d7b0: 20 20 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52    Thus INSERT OR
d7c0: 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52   FAIL, INSERT OR
d7d0: 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20   IGNORE, INSERT 
d7e0: 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20  OR ROLLBACK,.** 
d7f0: 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42  and INSERT OR AB
d800: 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e  ORT make no chan
d810: 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72  ges to the retur
d820: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a  n value of this.
d830: 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20  ** routine when 
d840: 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20  their insertion 
d850: 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53  fails.  When INS
d860: 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
d870: 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
d880: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
d890: 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
d8a0: 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
d8b0: 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
d8c0: 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
d8d0: 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
d8e0: 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
d8f0: 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
d900: 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
d910: 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
d920: 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
d930: 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
d940: 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
d950: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  rface..**.** For
d960: 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
d970: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
d980: 6e 20 49 4e 53 45 52 54 20 69 73 20 63 6f 6e 73  n INSERT is cons
d990: 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
d9a0: 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
d9b0: 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
d9c0: 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
d9d0: 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  k..**.** INVARIA
d9e0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  NTS:.**.** {H122
d9f0: 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  21} The [sqlite3
da00: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
da10: 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72  id()] function r
da20: 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64  eturns the rowid
da30: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
da40: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
da50: 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52  successful INSER
da60: 54 20 70 65 72 66 6f 72 6d 65 64 20 6f 6e 20 74  T performed on t
da70: 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
da80: 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
da90: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 77 69  nnection] and wi
daa0: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  thin the same or
dab0: 20 68 69 67 68 65 72 20 6c 65 76 65 6c 0a 2a 2a   higher level.**
dac0: 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65            trigge
dad0: 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65  r context, or ze
dae0: 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65  ro if there have
daf0: 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69 66 79   been no qualify
db00: 69 6e 67 20 69 6e 73 65 72 74 73 2e 0a 2a 2a 0a  ing inserts..**.
db10: 2a 2a 20 7b 48 31 32 32 32 33 7d 20 54 68 65 20  ** {H12223} The 
db20: 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
db30: 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75  sert_rowid()] fu
db40: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
db50: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  he.**          s
db60: 61 6d 65 20 76 61 6c 75 65 20 77 68 65 6e 20 63  ame value when c
db70: 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
db80: 61 6d 65 20 74 72 69 67 67 65 72 20 63 6f 6e 74  ame trigger cont
db90: 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ext.**          
dba0: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
dbb0: 72 65 20 61 6e 64 20 61 66 74 65 72 20 61 20 52  re and after a R
dbc0: 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 41  OLLBACK..**.** A
dbd0: 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
dbe0: 2a 20 7b 41 31 32 32 33 32 7d 20 49 66 20 61 20  * {A12232} If a 
dbf0: 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
dc00: 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 49  performs a new I
dc10: 4e 53 45 52 54 20 6f 6e 20 74 68 65 20 73 61 6d  NSERT on the sam
dc20: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61  e.**          da
dc30: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
dc40: 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c  n while the [sql
dc50: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
dc60: 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20  _rowid()].**    
dc70: 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 69        function i
dc80: 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
dc90: 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
dca0: 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64  ast insert rowid
dcb0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
dcc0: 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
dcd0: 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
dce0: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
dcf0: 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20  wid()] is.**    
dd00: 20 20 20 20 20 20 75 6e 70 72 65 64 69 63 74 61        unpredicta
dd10: 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
dd20: 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
dd30: 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
dd40: 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61  w.**          la
dd50: 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2e  st insert rowid.
dd60: 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
dd70: 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
dd80: 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
dd90: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
dda0: 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
ddb0: 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
ddc0: 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34   Modified {H1224
ddd0: 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a  0} <S10600>.**.*
dde0: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
ddf0: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
de00: 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72  er of database r
de10: 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68  ows that were ch
de20: 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65  anged.** or inse
de30: 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20  rted or deleted 
de40: 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
de50: 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53  ntly completed S
de60: 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
de70: 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
de80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
de90: 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  cified by the fi
dea0: 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
deb0: 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74  * Only changes t
dec0: 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79  hat are directly
ded0: 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
dee0: 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  e INSERT, UPDATE
def0: 2c 0a 2a 2a 20 6f 72 20 44 45 4c 45 54 45 20 73  ,.** or DELETE s
df00: 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
df10: 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
df20: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
df30: 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 61  by.** triggers a
df40: 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
df50: 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  Use the [sqlite3
df60: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
df70: 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f  ] function.** to
df80: 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20   find the total 
df90: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
dfa0: 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e  s including chan
dfb0: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72  ges caused by tr
dfc0: 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  iggers..**.** A 
dfd0: 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20  "row change" is 
dfe0: 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69  a change to a si
dff0: 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69  ngle row of a si
e000: 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61  ngle table.** ca
e010: 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52  used by an INSER
e020: 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50  T, DELETE, or UP
e030: 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20  DATE statement. 
e040: 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72   Rows that.** ar
e050: 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64  e changed as sid
e060: 65 20 65 66 66 65 63 74 73 20 6f 66 20 52 45 50  e effects of REP
e070: 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20  LACE constraint 
e080: 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72  resolution,.** r
e090: 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70  ollback, ABORT p
e0a0: 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f 50 20  rocessing, DROP 
e0b0: 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79  TABLE, or by any
e0c0: 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e   other.** mechan
e0d0: 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  isms do not coun
e0e0: 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20  t as direct row 
e0f0: 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  changes..**.** A
e100: 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
e110: 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
e120: 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
e130: 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
e140: 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
e150: 70 74 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e  pt of a trigger.
e160: 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65    Most SQL state
e170: 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61  ments are.** eva
e180: 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f  luated outside o
e190: 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20  f any trigger.  
e1a0: 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70  This is the "top
e1b0: 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67   level".** trigg
e1c0: 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20  er context.  If 
e1d0: 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20  a trigger fires 
e1e0: 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
e1f0: 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69  el, a.** new tri
e200: 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20  gger context is 
e210: 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20  entered for the 
e220: 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74  duration of that
e230: 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e   one.** trigger.
e240: 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72    Subtriggers cr
e250: 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73  eate subcontexts
e260: 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74   for their durat
e270: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69  ion..**.** Calli
e280: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
e290: 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
e2a0: 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
e2b0: 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
e2c0: 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
e2d0: 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
e2e0: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
e2f0: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
e300: 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72  mber of direct r
e310: 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ow changes in th
e320: 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74  e.** most recent
e330: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
e340: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
e350: 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
e360: 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20  same.** trigger 
e370: 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54  context..**.** T
e380: 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64  hus, when called
e390: 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
e3a0: 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69  vel, this functi
e3b0: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  on returns the.*
e3c0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  * number of chan
e3d0: 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
e3e0: 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
e3f0: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
e400: 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63  .** that also oc
e410: 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f  curred at the to
e420: 70 20 6c 65 76 65 6c 2e 20 20 57 69 74 68 69 6e  p level.  Within
e430: 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74   the body of a t
e440: 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73  rigger,.** the s
e450: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
e460: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
e470: 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64  e called to find
e480: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
e490: 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  * changes in the
e4a0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
e4b0: 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
e4c0: 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
e4d0: 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
e4e0: 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  within the body 
e4f0: 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  of the same trig
e500: 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ger..** However,
e510: 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75   the number retu
e520: 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
e530: 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a  clude changes.**
e540: 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72   caused by subtr
e550: 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f  iggers since tho
e560: 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77  se have their ow
e570: 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  n context..**.**
e580: 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e   SQLite implemen
e590: 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22  ts the command "
e5a0: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
e5b0: 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45  e" without a WHE
e5c0: 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20  RE clause.** by 
e5d0: 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63  dropping and rec
e5e0: 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c  reating the tabl
e5f0: 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63  e.  (This is muc
e600: 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f  h faster than go
e610: 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  ing.** through a
e620: 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69  nd deleting indi
e630: 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20  vidual elements 
e640: 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29  from the table.)
e650: 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 69    Because of thi
e660: 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f  s.** optimizatio
e670: 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73  n, the deletions
e680: 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d   in "DELETE FROM
e690: 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20   table" are not 
e6a0: 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a  row changes and.
e6b0: 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63  ** will not be c
e6c0: 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73 71  ounted by the sq
e6d0: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
e6e0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  or [sqlite3_tota
e6f0: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20  l_changes()].** 
e700: 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72  functions, regar
e710: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d  dless of the num
e720: 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20  ber of elements 
e730: 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e  that were origin
e740: 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74  ally.** in the t
e750: 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e  able.  To get an
e760: 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20   accurate count 
e770: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
e780: 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75   rows deleted, u
e790: 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52  se.** "DELETE FR
e7a0: 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31  OM table WHERE 1
e7b0: 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a  " instead..**.**
e7c0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
e7d0: 2a 2a 20 7b 48 31 32 32 34 31 7d 20 54 68 65 20  ** {H12241} The 
e7e0: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
e7f0: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61  ()] function sha
e800: 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 6e 75  ll return the nu
e810: 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20  mber of.**      
e820: 20 20 20 20 72 6f 77 20 63 68 61 6e 67 65 73 20      row changes 
e830: 63 61 75 73 65 64 20 62 79 20 74 68 65 20 6d 6f  caused by the mo
e840: 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
e850: 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 20 20 20  , UPDATE,.**    
e860: 20 20 20 20 20 20 6f 72 20 44 45 4c 45 54 45 20        or DELETE 
e870: 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65  statement on the
e880: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
e890: 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a  onnection and.**
e8a0: 20 20 20 20 20 20 20 20 20 20 77 69 74 68 69 6e            within
e8b0: 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67   the same or hig
e8c0: 68 65 72 20 74 72 69 67 67 65 72 20 63 6f 6e 74  her trigger cont
e8d0: 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20  ext, or zero if 
e8e0: 74 68 65 72 65 20 68 61 76 65 0a 2a 2a 20 20 20  there have.**   
e8f0: 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e 20         not been 
e900: 61 6e 79 20 71 75 61 6c 69 66 79 69 6e 67 20 72  any qualifying r
e910: 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a  ow changes..**.*
e920: 2a 20 7b 48 31 32 32 34 33 7d 20 53 74 61 74 65  * {H12243} State
e930: 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72  ments of the for
e940: 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  m "DELETE FROM t
e950: 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68 20 6e  ablename" with n
e960: 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 57 48  o.**          WH
e970: 45 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c 6c  ERE clause shall
e980: 20 63 61 75 73 65 20 73 75 62 73 65 71 75 65 6e   cause subsequen
e990: 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20  t calls to.**   
e9a0: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
e9b0: 63 68 61 6e 67 65 73 28 29 5d 20 74 6f 20 72 65  changes()] to re
e9c0: 74 75 72 6e 20 7a 65 72 6f 2c 20 72 65 67 61 72  turn zero, regar
e9d0: 64 6c 65 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  dless of the.** 
e9e0: 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
e9f0: 6f 66 20 72 6f 77 73 20 6f 72 69 67 69 6e 61 6c  of rows original
ea00: 6c 79 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e  ly in the table.
ea10: 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
ea20: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 35  NS:.**.** {A1225
ea30: 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65  2} If a separate
ea40: 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
ea50: 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
ea60: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
ea70: 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
ea80: 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33    while [sqlite3
ea90: 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
eaa0: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
eab0: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
eac0: 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75 6e  *          is un
ead0: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
eae0: 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
eaf0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
eb00: 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
eb10: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
eb20: 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
eb30: 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
eb40: 20 7b 48 31 32 32 36 30 7d 20 3c 53 31 30 36 30   {H12260} <S1060
eb50: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
eb60: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
eb70: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
eb80: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
eb90: 62 79 20 49 4e 53 45 52 54 2c 0a 2a 2a 20 55 50  by INSERT,.** UP
eba0: 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
ebb0: 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
ebc0: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
ebd0: 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70  nnection] was op
ebe0: 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 63 6f 75  ened..** The cou
ebf0: 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  nt includes all 
ec00: 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c  changes from all
ec10: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
ec20: 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  s.  However,.** 
ec30: 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  the count does n
ec40: 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
ec50: 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  es used to imple
ec60: 6d 65 6e 74 20 52 45 50 4c 41 43 45 20 63 6f 6e  ment REPLACE con
ec70: 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20  straints,.** do 
ec80: 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f  rollbacks or ABO
ec90: 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f  RT processing, o
eca0: 72 20 44 52 4f 50 20 74 61 62 6c 65 20 70 72 6f  r DROP table pro
ecb0: 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20  cessing..** The 
ecc0: 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e  changes are coun
ecd0: 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
ece0: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
ecf0: 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 0a  t makes them is.
ed00: 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68  ** completed (wh
ed10: 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
ed20: 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73 65   handle is passe
ed30: 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
ed40: 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
ed50: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
ed60: 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ])..**.** SQLite
ed70: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
ed80: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20  command "DELETE 
ed90: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68  FROM table" with
eda0: 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75  out a WHERE clau
edb0: 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e  se.** by droppin
edc0: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67  g and recreating
edd0: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68   the table.  (Th
ede0: 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 74 65  is is much faste
edf0: 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20  r than going.** 
ee00: 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65  through and dele
ee10: 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20  ting individual 
ee20: 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68  elements from th
ee30: 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75  e table.)  Becau
ee40: 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70  se of this.** op
ee50: 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20  timization, the 
ee60: 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45  deletions in "DE
ee70: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
ee80: 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61   are not row cha
ee90: 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c  nges and.** will
eea0: 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20   not be counted 
eeb0: 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  by the sqlite3_c
eec0: 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c  hanges() or [sql
eed0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
eee0: 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  es()].** functio
eef0: 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ns, regardless o
ef00: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
ef10: 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65  elements that we
ef20: 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  re originally.**
ef30: 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20   in the table.  
ef40: 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61  To get an accura
ef50: 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20  te count of the 
ef60: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64  number of rows d
ef70: 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22  eleted, use.** "
ef80: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
ef90: 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65  e WHERE 1" inste
efa0: 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ad..**.** See al
efb0: 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
efc0: 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
efd0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  face..**.** INVA
efe0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
eff0: 31 32 32 36 31 7d 20 54 68 65 20 5b 73 71 6c 69  12261} The [sqli
f000: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
f010: 73 28 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65  s()] returns the
f020: 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a   total number.**
f030: 20 20 20 20 20 20 20 20 20 20 6f 66 20 72 6f 77            of row
f040: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
f050: 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  by INSERT, UPDAT
f060: 45 2c 20 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45  E, and/or DELETE
f070: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61  .**          sta
f080: 74 65 6d 65 6e 74 73 20 6f 6e 20 74 68 65 20 73  tements on the s
f090: 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
f0a0: 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e  nnection], in an
f0b0: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72  y.**          tr
f0c0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 73  igger context, s
f0d0: 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
f0e0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73  e connection was
f0f0: 20 63 72 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   created..**.** 
f100: 7b 48 31 32 32 36 33 7d 20 53 74 61 74 65 6d 65  {H12263} Stateme
f110: 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  nts of the form 
f120: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
f130: 6c 65 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a  lename" with no.
f140: 2a 2a 20 20 20 20 20 20 20 20 20 20 57 48 45 52  **          WHER
f150: 45 20 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e  E clause shall n
f160: 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
f170: 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
f180: 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c           by [sql
f190: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
f1a0: 65 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53  es()]..**.** ASS
f1b0: 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
f1c0: 7b 41 31 32 32 36 34 7d 20 49 66 20 61 20 73 65  {A12264} If a se
f1d0: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
f1e0: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
f1f0: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
f200: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
f210: 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73          while [s
f220: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
f230: 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
f240: 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
f250: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
f260: 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
f270: 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
f280: 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
f290: 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
f2a0: 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
f2b0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
f2c0: 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
f2d0: 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
f2e0: 65 72 79 20 7b 48 31 32 32 37 30 7d 20 3c 53 33  ery {H12270} <S3
f2f0: 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0500>.**.** This
f300: 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
f310: 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
f320: 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
f330: 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
f340: 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
f350: 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
f360: 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
f370: 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
f380: 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
f390: 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
f3a0: 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
f3b0: 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
f3c0: 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
f3d0: 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
f3e0: 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
f3f0: 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
f400: 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
f410: 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65  **.** It is safe
f420: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
f430: 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
f440: 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
f450: 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
f460: 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
f470: 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
f480: 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
f490: 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
f4a0: 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
f4b0: 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
f4c0: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
f4d0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
f4e0: 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
f4f0: 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
f500: 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
f510: 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
f520: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c  .**.** If an SQL
f530: 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
f540: 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
f550: 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
f560: 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
f570: 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
f580: 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
f590: 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
f5a0: 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
f5b0: 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
f5c0: 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
f5d0: 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
f5e0: 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20  n..**.** An SQL 
f5f0: 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
f600: 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
f610: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
f620: 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
f630: 20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70   If the interrup
f640: 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
f650: 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
f660: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
f670: 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
f680: 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
f690: 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
f6a0: 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
f6b0: 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
f6c0: 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
f6d0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
f6e0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
f6f0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
f700: 28 29 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  () has no effect
f710: 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
f720: 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
f730: 74 61 72 74 65 64 20 61 66 74 65 72 20 73 71 6c  tarted after sql
f740: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
f750: 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
f760: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
f770: 2a 20 7b 48 31 32 32 37 31 7d 20 54 68 65 20 5b  * {H12271} The [
f780: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f790: 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  t()] interface w
f7a0: 69 6c 6c 20 66 6f 72 63 65 20 61 6c 6c 20 72 75  ill force all ru
f7b0: 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  nning.**        
f7c0: 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73    SQL statements
f7d0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
f7e0: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
f7f0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
f800: 20 20 20 20 20 20 20 20 20 20 74 6f 20 68 61 6c            to hal
f810: 74 20 61 66 74 65 72 20 70 72 6f 63 65 73 73 69  t after processi
f820: 6e 67 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61  ng at most one a
f830: 64 64 69 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66  dditional row of
f840: 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   data..**.** {H1
f850: 32 32 37 32 7d 20 41 6e 79 20 53 51 4c 20 73 74  2272} Any SQL st
f860: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20  atement that is 
f870: 69 6e 74 65 72 72 75 70 74 65 64 20 62 79 20 5b  interrupted by [
f880: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f890: 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  t()].**         
f8a0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
f8b0: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
f8c0: 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
f8d0: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 37  NS:.**.** {A1227
f8e0: 39 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61  9} If the databa
f8f0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
f900: 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
f910: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
f920: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
f930: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
f940: 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
f950: 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
f960: 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
f970: 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
f980: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f990: 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
f9a0: 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
f9b0: 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 48 31 30  Is Complete {H10
f9c0: 35 31 30 7d 20 3c 53 37 30 32 30 30 3e 0a 2a 2a  510} <S70200>.**
f9d0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
f9e0: 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  es are useful fo
f9f0: 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  r command-line i
fa00: 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
fa10: 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
fa20: 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
fa30: 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
fa40: 20 63 6f 6d 70 6c 65 74 65 20 61 20 53 51 4c 20   complete a SQL 
fa50: 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
fa60: 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
fa70: 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
fa80: 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
fa90: 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
faa0: 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
fab0: 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
fac0: 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66  s return true if
fad0: 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
fae0: 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
faf0: 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
fb00: 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 20  L statement.  A 
fb10: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
fb20: 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
fb30: 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
fb40: 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
fb50: 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
fb60: 6f 74 20 61 20 66 72 61 67 6d 65 6e 74 20 6f 66  ot a fragment of
fb70: 20 61 0a 2a 2a 20 43 52 45 41 54 45 20 54 52 49   a.** CREATE TRI
fb80: 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
fb90: 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74   Semicolons that
fba0: 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
fbb0: 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
fbc0: 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
fbd0: 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
fbe0: 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
fbf0: 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
fc00: 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
fc10: 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
fc20: 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
fc30: 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
fc40: 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
fc50: 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
fc60: 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
fc70: 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  minator..**.** T
fc80: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
fc90: 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
fca0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  QL statements th
fcb0: 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64  us.** will not d
fcc0: 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
fcd0: 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
fce0: 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  L..**.** INVARIA
fcf0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35  NTS:.**.** {H105
fd00: 31 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  11} A successful
fd10: 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b   evaluation of [
fd20: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
fd30: 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
fd40: 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70     [sqlite3_comp
fd50: 6c 65 74 65 31 36 28 29 5d 20 66 75 6e 63 74 69  lete16()] functi
fd60: 6f 6e 73 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20  ons shall.**    
fd70: 20 20 20 20 20 20 72 65 74 75 72 6e 20 61 20 6e        return a n
fd80: 75 6d 65 72 69 63 20 31 20 69 66 20 61 6e 64 20  umeric 1 if and 
fd90: 6f 6e 6c 79 20 69 66 20 74 68 65 20 6c 61 73 74  only if the last
fda0: 20 6e 6f 6e 2d 77 68 69 74 65 73 70 61 63 65 0a   non-whitespace.
fdb0: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 6b 65  **          toke
fdc0: 6e 20 69 6e 20 74 68 65 69 72 20 69 6e 70 75 74  n in their input
fdd0: 20 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20   is a semicolon 
fde0: 74 68 61 74 20 69 73 20 6e 6f 74 20 69 6e 20 62  that is not in b
fdf0: 65 74 77 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20  etween.**       
fe00: 20 20 20 74 68 65 20 42 45 47 49 4e 20 61 6e 64     the BEGIN and
fe10: 20 45 4e 44 20 6f 66 20 61 20 43 52 45 41 54 45   END of a CREATE
fe20: 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
fe30: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31  nt..**.** {H1051
fe40: 32 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61  2} If a memory a
fe50: 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
fe60: 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 61 6e  occurs during an
fe70: 20 69 6e 76 6f 63 61 74 69 6f 6e 0a 2a 2a 20 20   invocation.**  
fe80: 20 20 20 20 20 20 20 20 6f 66 20 5b 73 71 6c 69          of [sqli
fe90: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
fea0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  or [sqlite3_comp
feb0: 6c 65 74 65 31 36 28 29 5d 20 74 68 65 6e 20 74  lete16()] then t
fec0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
fed0: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74  outine shall ret
fee0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  urn [SQLITE_NOME
fef0: 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  M]..**.** ASSUMP
ff00: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
ff10: 30 35 31 32 7d 20 54 68 65 20 69 6e 70 75 74 20  0512} The input 
ff20: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
ff30: 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
ff40: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
ff50: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54  d.**          UT
ff60: 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
ff70: 2a 20 7b 41 31 30 35 31 33 7d 20 54 68 65 20 69  * {A10513} The i
ff80: 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
ff90: 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
ffa0: 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
ffb0: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
ffc0: 20 20 20 20 20 55 54 46 2d 31 36 20 73 74 72 69       UTF-16 stri
ffd0: 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
ffe0: 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
fff0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
10000 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
10010 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
10020 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
10030 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
10040 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
10050 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
10060 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
10070 45 5f 42 55 53 59 20 45 72 72 6f 72 73 20 7b 48  E_BUSY Errors {H
10080 31 32 33 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a  12310} <S40400>.
10090 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
100a0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
100b0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
100c0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
100d0 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  d whenever.** an
100e0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
100f0 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
10100 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61  ase table that a
10110 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
10120 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
10130 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  locked..**.** If
10140 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
10150 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
10160 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
10170 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
10180 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
10190 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
101a0 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
101b0 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
101c0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
101d0 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
101e0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
101f0 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69  llback will be i
10200 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
10210 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
10220 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
10230 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c  ent to the handl
10240 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
10250 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
10260 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
10270 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
10280 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
10290 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 54 68 65  _handler().  The
102a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
102b0 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c   to.** the handl
102c0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
102d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
102e0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
102f0 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
10300 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
10310 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
10320 65 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20  ent.  If the.** 
10330 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
10340 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
10350 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
10360 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
10370 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
10380 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
10390 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
103a0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
103b0 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
103c0 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62  .** If the callb
103d0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
103e0 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
103f0 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
10400 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
10410 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
10420 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63  eading and the c
10430 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
10440 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
10450 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
10460 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
10470 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
10480 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
10490 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
104a0 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
104b0 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
104c0 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
104d0 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
104e0 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
104f0 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
10500 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
10510 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
10520 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
10530 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
10540 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
10550 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
10560 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
10570 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
10580 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
10590 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
105a0 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
105b0 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
105c0 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
105d0 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
105e0 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
105f0 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
10600 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
10610 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
10620 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
10630 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
10640 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
10650 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
10660 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
10670 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
10680 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
10690 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
106a0 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
106b0 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
106c0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
106d0 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
106e0 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
106f0 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
10700 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
10710 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
10720 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
10730 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
10740 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
10750 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
10760 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
10770 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
10780 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
10790 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
107a0 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
107b0 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
107c0 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
107d0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
107e0 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
107f0 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75  * The default bu
10800 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
10810 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ULL..**.** The [
10820 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
10830 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
10840 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
10850 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
10860 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
10870 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
10880 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
10890 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
108a0 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
108b0 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
108c0 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
108d0 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
108e0 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
108f0 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
10900 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
10910 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
10920 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
10930 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
10940 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
10950 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
10960 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
10970 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
10980 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
10990 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
109a0 65 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69  eaders.  If it i
109b0 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
109c0 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
109d0 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
109e0 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
109f0 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
10a00 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
10a10 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
10a20 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
10a30 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
10a40 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
10a50 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
10a60 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
10a70 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
10a80 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69  R_BLOCKED].  Thi
10a90 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
10aa0 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
10ab0 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
10ac0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
10ad0 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
10ae0 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73  ** <a href="/cvs
10af0 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72  trac/wiki?p=Corr
10b00 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
10b10 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f  usyError">.** Co
10b20 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
10b30 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77  gBusyError</a> w
10b40 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64  iki page for a d
10b50 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79  iscussion of why
10b60 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f  .** this is impo
10b70 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rtant..**.** The
10b80 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
10b90 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
10ba0 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
10bb0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
10bc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
10bd0 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
10be0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
10bf0 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
10c00 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
10c10 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c  .  Note that cal
10c20 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
10c30 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
10c40 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
10c50 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79  r clear the busy
10c60 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
10c70 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
10c80 2a 20 7b 48 31 32 33 31 31 7d 20 54 68 65 20 5b  * {H12311} The [
10c90 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
10ca0 64 6c 65 72 28 44 2c 43 2c 41 29 5d 20 66 75 6e  dler(D,C,A)] fun
10cb0 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 70 6c  ction shall repl
10cc0 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ace.**          
10cd0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 6e  busy callback in
10ce0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
10cf0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 69 74  onnection] D wit
10d00 68 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20  h a new.**      
10d10 20 20 20 20 61 20 6e 65 77 20 62 75 73 79 20 68      a new busy h
10d20 61 6e 64 6c 65 72 20 43 20 61 6e 64 20 61 70 70  andler C and app
10d30 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
10d40 69 6e 74 65 72 20 41 2e 0a 2a 2a 0a 2a 2a 20 7b  inter A..**.** {
10d50 48 31 32 33 31 32 7d 20 4e 65 77 6c 79 20 63 72  H12312} Newly cr
10d60 65 61 74 65 64 20 5b 64 61 74 61 62 61 73 65 20  eated [database 
10d70 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61  connections] sha
10d80 6c 6c 20 68 61 76 65 20 61 20 62 75 73 79 0a 2a  ll have a busy.*
10d90 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e 64 6c  *          handl
10da0 65 72 20 6f 66 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  er of NULL..**.*
10db0 2a 20 7b 48 31 32 33 31 34 7d 20 57 68 65 6e 20  * {H12314} When 
10dc0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 5b 64 61 74  two or more [dat
10dd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10de0 73 5d 20 73 68 61 72 65 20 61 0a 2a 2a 20 20 20  s] share a.**   
10df0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
10e00 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
10e10 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63  che | common cac
10e20 68 65 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  he],.**         
10e30 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
10e40 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
10e50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75  se connection cu
10e60 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 0a 2a 2a  rrently using.**
10e70 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61            the ca
10e80 63 68 65 20 73 68 61 6c 6c 20 62 65 20 69 6e 76  che shall be inv
10e90 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 63 61  oked when the ca
10ea0 63 68 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  che encounters a
10eb0 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   lock..**.** {H1
10ec0 32 33 31 36 7d 20 49 66 20 61 20 62 75 73 79 20  2316} If a busy 
10ed0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
10ee0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
10ef0 68 65 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69  hen the SQLite i
10f00 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20  nterface.**     
10f10 20 20 20 20 20 74 68 61 74 20 70 72 6f 76 6f 6b       that provok
10f20 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e 67 20 65  ed the locking e
10f30 76 65 6e 74 20 73 68 61 6c 6c 20 72 65 74 75 72  vent shall retur
10f40 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  n [SQLITE_BUSY].
10f50 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 38 7d 20  .**.** {H12318} 
10f60 53 51 4c 69 74 65 20 73 68 61 6c 6c 20 69 6e 76  SQLite shall inv
10f70 6f 6b 65 73 20 74 68 65 20 62 75 73 79 20 68 61  okes the busy ha
10f80 6e 64 6c 65 72 20 77 69 74 68 20 74 77 6f 20 61  ndler with two a
10f90 72 67 75 6d 65 6e 74 73 20 77 68 69 63 68 0a 2a  rguments which.*
10fa0 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 61  *          are a
10fb0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 6f 69   copy of the poi
10fc0 6e 74 65 72 20 73 75 70 70 6c 69 65 64 20 62 79  nter supplied by
10fd0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
10fe0 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
10ff0 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f    [sqlite3_busy_
11000 68 61 6e 64 6c 65 72 28 29 5d 20 61 6e 64 20 61  handler()] and a
11010 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75   count of the nu
11020 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 0a 2a 2a  mber of prior.**
11030 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61            invoca
11040 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 73  tions of the bus
11050 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68  y handler for th
11060 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65  e same locking e
11070 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  vent..**.** ASSU
11080 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
11090 41 31 32 33 31 39 7d 20 41 20 62 75 73 79 20 68  A12319} A busy h
110a0 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
110b0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
110c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
110d0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 70 72            or [pr
110e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
110f0 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
11100 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
11110 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
11120 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
11130 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
11140 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
11150 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11160 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
11170 6d 65 6f 75 74 20 7b 48 31 32 33 34 30 7d 20 3c  meout {H12340} <
11180 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40410>.**.** Th
11190 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
111a0 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
111b0 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
111c0 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
111d0 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
111e0 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
111f0 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
11200 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54  le is locked.  T
11210 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
11220 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
11230 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
11240 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
11250 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
11260 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
11270 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31 32 33 34  umulated. {H1234
11280 33 7d 20 41 66 74 65 72 20 22 6d 73 22 20 6d 69  3} After "ms" mi
11290 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
112a0 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
112b0 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
112c0 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
112d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
112e0 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
112f0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
11300 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
11310 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69  ED]..**.** Calli
11320 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
11330 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
11340 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
11350 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
11360 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
11370 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
11380 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  * There can only
11390 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
113a0 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
113b0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
113c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
113d0 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65  on] any any give
113e0 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
113f0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
11400 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
11410 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
11420 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
11430 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
11440 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
11450 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
11460 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
11470 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   cleared..**.** 
11480 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
11490 2a 20 7b 48 31 32 33 34 31 7d 20 54 68 65 20 5b  * {H12341} The [
114a0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
114b0 65 6f 75 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e  eout()] function
114c0 20 73 68 61 6c 6c 20 6f 76 65 72 72 69 64 65 20   shall override 
114d0 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20  any prior.**    
114e0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
114f0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 6f  usy_timeout()] o
11500 72 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  r [sqlite3_busy_
11510 68 61 6e 64 6c 65 72 28 29 5d 20 73 65 74 74 69  handler()] setti
11520 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ng.**          o
11530 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
11540 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11550 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 33 7d  ..**.** {H12343}
11560 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   If the 2nd para
11570 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
11580 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
11590 5d 20 69 73 20 6c 65 73 73 20 74 68 61 6e 0a 2a  ] is less than.*
115a0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 65 71  *          or eq
115b0 75 61 6c 20 74 6f 20 7a 65 72 6f 2c 20 74 68 65  ual to zero, the
115c0 6e 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  n the busy handl
115d0 65 72 20 73 68 61 6c 6c 20 62 65 20 63 6c 65 61  er shall be clea
115e0 72 65 64 20 73 6f 20 74 68 61 74 0a 2a 2a 20 20  red so that.**  
115f0 20 20 20 20 20 20 20 20 61 6c 6c 20 73 75 62 73          all subs
11600 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e 67 20 65  equent locking e
11610 76 65 6e 74 73 20 69 6d 6d 65 64 69 61 74 65 6c  vents immediatel
11620 79 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  y return [SQLITE
11630 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _BUSY]..**.** {H
11640 31 32 33 34 34 7d 20 49 66 20 74 68 65 20 32 6e  12344} If the 2n
11650 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
11660 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
11670 65 6f 75 74 28 29 5d 20 69 73 20 61 20 70 6f 73  eout()] is a pos
11680 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  itive.**        
11690 20 20 6e 75 6d 62 65 72 20 4e 2c 20 74 68 65 6e    number N, then
116a0 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
116b0 73 68 61 6c 6c 20 62 65 20 73 65 74 20 74 68 61  shall be set tha
116c0 74 20 72 65 70 65 61 74 65 64 6c 79 20 63 61 6c  t repeatedly cal
116d0 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ls.**          t
116e0 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
116f0 6f 64 20 69 6e 20 74 68 65 20 5b 73 71 6c 69 74  od in the [sqlit
11700 65 33 5f 76 66 73 20 7c 20 56 46 53 20 69 6e 74  e3_vfs | VFS int
11710 65 72 66 61 63 65 5d 20 75 6e 74 69 6c 0a 2a 2a  erface] until.**
11720 20 20 20 20 20 20 20 20 20 20 65 69 74 68 65 72            either
11730 20 74 68 65 20 6c 6f 63 6b 20 63 6c 65 61 72 73   the lock clears
11740 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 63 75   or until the cu
11750 6d 75 6c 61 74 69 76 65 20 73 6c 65 65 70 20 74  mulative sleep t
11760 69 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ime.**          
11770 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 62 79  reported back by
11780 20 78 53 6c 65 65 70 28 29 20 65 78 63 65 65 64   xSleep() exceed
11790 73 20 4e 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  s N milliseconds
117a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
117b0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
117c0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
117d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
117e0 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
117f0 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
11800 6e 67 20 51 75 65 72 69 65 73 20 7b 48 31 32 33  ng Queries {H123
11810 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a  70} <S10000>.**.
11820 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
11830 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
11840 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
11850 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
11860 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
11870 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
11880 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
11890 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
118a0 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
118b0 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
118c0 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
118d0 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
118e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
118f0 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
11900 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
11910 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
11920 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
11930 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
11940 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
11950 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
11960 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
11970 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
11980 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
11990 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
119a0 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
119b0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
119c0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
119d0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
119e0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
119f0 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
11a00 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
11a10 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
11a20 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
11a30 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
11a40 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
11a50 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
11a60 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
11a70 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
11a80 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
11a90 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
11aa0 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
11ab0 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
11ac0 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
11ad0 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
11ae0 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
11af0 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
11b00 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
11b10 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
11b20 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
11b30 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
11b40 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
11b50 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
11b60 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
11b70 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
11b80 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
11b90 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
11ba0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
11bb0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
11bc0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
11bd0 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
11be0 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
11bf0 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
11c00 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
11c10 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
11c20 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
11c30 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
11c40 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
11c50 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c  .** As an exampl
11c60 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
11c70 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
11c80 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
11c90 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
11ca0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
11cb0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
11cc0 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
11cd0 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
11ce0 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
11cf0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
11d00 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
11d10 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
11d20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
11d30 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
11d40 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
11d50 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
11d60 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
11d70 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
11d80 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
11d90 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
11da0 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
11db0 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
11dc0 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
11dd0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
11de0 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
11df0 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
11e00 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
11e10 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
11e20 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
11e30 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
11e40 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
11e50 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
11e60 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
11e70 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
11e80 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
11e90 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
11ea0 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
11eb0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
11ec0 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
11ed0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
11ee0 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
11ef0 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
11f00 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
11f10 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
11f20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
11f30 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
11f40 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
11f50 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
11f60 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
11f70 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
11f80 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
11f90 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
11fa0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
11fb0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
11fc0 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
11fd0 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
11fe0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
11ff0 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
12000 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
12010 65 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e  eter.  It return
12020 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
12030 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
12040 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
12050 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
12060 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63  *.** After the c
12070 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
12080 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
12090 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69  ng the result, i
120a0 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73  t should.** pass
120b0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
120c0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
120d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
120e0 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
120f0 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
12100 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
12110 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
12120 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
12130 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
12140 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
12150 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
12160 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
12170 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
12180 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
12190 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
121a0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
121b0 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
121c0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
121d0 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
121e0 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
121f0 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
12200 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
12210 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
12220 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
12230 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
12240 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
12250 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
12260 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
12270 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
12280 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
12290 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
122a0 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
122b0 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
122c0 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
122d0 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
122e0 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
122f0 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
12300 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
12310 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
12320 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
12330 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
12340 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
12350 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
12360 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
12370 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
12380 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
12390 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
123a0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
123b0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
123c0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
123d0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
123e0 32 33 37 31 7d 20 49 66 20 61 20 5b 73 71 6c 69  2371} If a [sqli
123f0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
12400 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f 72 79 20   fails a memory 
12410 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
12420 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74 20  .**          it 
12430 73 68 61 6c 6c 20 66 72 65 65 20 74 68 65 20 72  shall free the r
12440 65 73 75 6c 74 20 74 61 62 6c 65 20 75 6e 64 65  esult table unde
12450 72 20 63 6f 6e 73 74 72 75 63 74 69 6f 6e 2c 20  r construction, 
12460 61 62 6f 72 74 20 74 68 65 0a 2a 2a 20 20 20 20  abort the.**    
12470 20 20 20 20 20 20 71 75 65 72 79 20 69 6e 20 70        query in p
12480 72 6f 63 65 73 73 2c 20 73 6b 69 70 20 61 6e 79  rocess, skip any
12490 20 73 75 62 73 65 71 75 65 6e 74 20 71 75 65 72   subsequent quer
124a0 69 65 73 2c 20 73 65 74 20 74 68 65 0a 2a 2a 20  ies, set the.** 
124b0 20 20 20 20 20 20 20 20 20 2a 70 61 7a 52 65 73           *pazRes
124c0 75 6c 74 20 6f 75 74 70 75 74 20 70 6f 69 6e 74  ult output point
124d0 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e 64 20 72  er to NULL and r
124e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
124f0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  MEM]..**.** {H12
12500 33 37 33 7d 20 49 66 20 74 68 65 20 70 6e 43 6f  373} If the pnCo
12510 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65 72 20 74  lumn parameter t
12520 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  o [sqlite3_get_t
12530 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e  able()] is not N
12540 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
12550 74 68 65 6e 20 61 20 73 75 63 63 65 73 73 66 75  then a successfu
12560 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
12570 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
12580 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20  le()] shall.**  
12590 20 20 20 20 20 20 20 20 77 72 69 74 65 20 74 68          write th
125a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
125b0 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  mns in the.**   
125c0 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65         result se
125d0 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69  t of the query i
125e0 6e 74 6f 20 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a 2a  nto *pnColumn..*
125f0 2a 0a 2a 2a 20 7b 48 31 32 33 37 34 7d 20 49 66  *.** {H12374} If
12600 20 74 68 65 20 70 6e 52 6f 77 20 70 61 72 61 6d   the pnRow param
12610 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
12620 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73  _get_table()] is
12630 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20   not NULL.**    
12640 20 20 20 20 20 20 74 68 65 6e 20 61 20 73 75 63        then a suc
12650 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
12660 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67  on of [sqlite3_g
12670 65 74 5f 74 61 62 6c 65 28 29 5d 20 73 68 61 6c  et_table()] shal
12680 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 72  l.**          wr
12690 69 74 65 73 20 74 68 65 20 6e 75 6d 62 65 72 20  ites the number 
126a0 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65 0a 2a  of rows in the.*
126b0 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
126c0 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65  t set of the que
126d0 72 79 20 69 6e 74 6f 20 2a 70 6e 52 6f 77 2e 0a  ry into *pnRow..
126e0 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 36 7d 20 41  **.** {H12376} A
126f0 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
12700 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
12710 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
12720 74 68 61 74 20 63 6f 6d 70 75 74 65 73 0a 2a 2a  that computes.**
12730 20 20 20 20 20 20 20 20 20 20 4e 20 72 6f 77 73            N rows
12740 20 6f 66 20 72 65 73 75 6c 74 20 77 69 74 68 20   of result with 
12750 43 20 63 6f 6c 75 6d 6e 73 20 70 65 72 20 72 6f  C columns per ro
12760 77 20 73 68 61 6c 6c 20 6d 61 6b 65 20 2a 70 61  w shall make *pa
12770 7a 52 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 20  zResult.**      
12780 20 20 20 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20      point to an 
12790 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
127a0 73 20 74 6f 20 28 4e 2b 31 29 2a 43 20 73 74 72  s to (N+1)*C str
127b0 69 6e 67 73 20 77 68 65 72 65 20 74 68 65 20 66  ings where the f
127c0 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  irst.**         
127d0 20 43 20 73 74 72 69 6e 67 73 20 61 72 65 20 63   C strings are c
127e0 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 61 73 20 6f  olumn names as o
127f0 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
12800 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
12810 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
12820 20 61 6e 64 20 74 68 65 20 72 65 73 74 20 61 72   and the rest ar
12830 65 20 63 6f 6c 75 6d 6e 20 72 65 73 75 6c 74 20  e column result 
12840 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20  values.**       
12850 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d     obtained from
12860 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
12870 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
12880 7b 48 31 32 33 37 39 7d 20 54 68 65 20 76 61 6c  {H12379} The val
12890 75 65 73 20 69 6e 20 74 68 65 20 70 61 7a 52 65  ues in the pazRe
128a0 73 75 6c 74 20 61 72 72 61 79 20 72 65 74 75 72  sult array retur
128b0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
128c0 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20  get_table()].** 
128d0 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72           shall r
128e0 65 6d 61 69 6e 20 76 61 6c 69 64 20 75 6e 74 69  emain valid unti
128f0 6c 20 63 6c 65 61 72 65 64 20 62 79 20 5b 73 71  l cleared by [sq
12900 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
12910 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  ()]..**.** {H123
12920 38 32 7d 20 57 68 65 6e 20 61 6e 20 65 72 72 6f  82} When an erro
12930 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
12940 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73  evaluation of [s
12950 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
12960 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
12970 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 73 68 61  the function sha
12980 6c 6c 20 73 65 74 20 2a 70 61 7a 52 65 73 75 6c  ll set *pazResul
12990 74 20 74 6f 20 4e 55 4c 4c 2c 20 77 72 69 74 65  t to NULL, write
129a0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
129b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
129c0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
129d0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
129e0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 6d 61 6b 65  _malloc()], make
129f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 2a 70  .**          **p
12a00 7a 45 72 72 6d 73 67 20 70 6f 69 6e 74 20 74 6f  zErrmsg point to
12a10 20 74 68 61 74 20 65 72 72 6f 72 20 6d 65 73 73   that error mess
12a20 61 67 65 2c 20 61 6e 64 20 72 65 74 75 72 6e 20  age, and return 
12a30 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 70  a.**          ap
12a40 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
12a50 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
12a60 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
12a70 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
12a80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
12a90 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
12aa0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
12ab0 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
12ac0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
12ad0 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
12ae0 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
12af0 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
12b00 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
12b10 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
12b20 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
12b30 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
12b40 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
12b50 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
12b60 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
12b70 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
12b80 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
12b90 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
12ba0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
12bb0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
12bc0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
12bd0 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
12be0 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
12bf0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
12c00 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
12c10 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  nting Functions 
12c20 7b 48 31 37 34 30 30 7d 20 3c 53 37 30 30 30 30  {H17400} <S70000
12c30 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S20000>.**.** 
12c40 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
12c50 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66  re workalikes of
12c60 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
12c70 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
12c80 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
12c90 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
12ca0 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ry..**.** The sq
12cb0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
12cc0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
12cd0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
12ce0 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
12cf0 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
12d00 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
12d10 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
12d20 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
12d30 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
12d40 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
12d50 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
12d60 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
12d70 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 42  ite3_free()].  B
12d80 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
12d90 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
12da0 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
12db0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
12dc0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
12dd0 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
12de0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
12df0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
12e00 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65  .**.** In sqlite
12e10 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
12e20 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
12e30 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
12e40 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
12e50 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
12e60 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
12e70 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
12e80 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
12e90 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
12ea0 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
12eb0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
12ec0 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
12ed0 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
12ee0 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
12ef0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
12f00 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
12f10 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
12f20 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20  printf().  This 
12f30 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
12f40 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
12f50 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
12f60 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
12f70 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
12f80 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
12f90 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
12fa0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
12fb0 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
12fc0 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
12fd0 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
12fe0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
12ff0 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
13000 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
13010 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20 57  o the buffer.  W
13020 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
13030 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
13040 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
13050 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
13060 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
13070 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
13080 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
13090 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
130a0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
130b0 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
130c0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
130d0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
130e0 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  ** As long as th
130f0 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
13100 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
13110 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
13120 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
13130 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
13140 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
13150 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
13160 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   The first.** pa
13170 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
13180 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
13190 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
131a0 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
131b0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
131c0 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
131d0 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
131e0 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
131f0 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
13200 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
13210 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
13220 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
13230 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
13240 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
13250 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
13260 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
13270 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
13280 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
13290 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
132a0 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
132b0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
132c0 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
132d0 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
132e0 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
132f0 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
13300 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
13310 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
13320 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
13330 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
13340 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65  a null-terminate
13350 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
13360 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
13370 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
13380 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
13390 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
133a0 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
133b0 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
133c0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
133d0 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  .  By doubling e
133e0 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
133f0 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
13400 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
13410 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
13420 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
13430 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
13440 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
13450 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
13460 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
13470 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
13480 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
13490 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
134a0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
134b0 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
134c0 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
134d0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
134e0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
134f0 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
13500 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
13510 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
13520 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
13530 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
13540 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
13550 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
13560 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
13570 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
13580 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
13590 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
135a0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
135b0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
135c0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
135d0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
135e0 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
135f0 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
13600 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
13610 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
13620 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
13630 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
13640 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
13650 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
13660 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
13670 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
13680 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
13690 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
136a0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
136b0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
136c0 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
136d0 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
136e0 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
136f0 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
13700 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
13710 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
13720 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
13730 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
13740 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
13750 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
13760 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
13770 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
13780 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
13790 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
137a0 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
137b0 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
137c0 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
137d0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
137e0 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
137f0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
13800 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
13810 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
13820 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77   The %Q option w
13830 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
13840 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
13850 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
13860 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
13870 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
13880 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
13890 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
138a0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
138b0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
138c0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
138d0 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
138e0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
138f0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
13900 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 20 69  single quotes) i
13910 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25  n place of the %
13920 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c 20 66  Q option.  So, f
13930 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
13940 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
13950 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
13960 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
13970 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
13980 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
13990 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
139a0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
139b0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
139c0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
139d0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
139e0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
139f0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
13a00 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
13a10 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
13a20 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
13a30 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
13a40 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
13a50 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
13a60 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
13a70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
13a80 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 6f  *.** The "%z" fo
13a90 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
13aa0 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c 69  works exactly li
13ab0 6b 65 20 22 25 73 22 20 77 69 74 68 20 74 68 65  ke "%s" with the
13ac0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
13ad0 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
13ae0 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
13af0 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
13b00 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
13b10 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
13b20 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
13b30 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 20  e input string. 
13b40 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  {END}.**.** INVA
13b50 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
13b60 31 37 34 30 33 7d 20 20 54 68 65 20 5b 73 71 6c  17403}  The [sql
13b70 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20  ite3_mprintf()] 
13b80 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 6d 70  and [sqlite3_vmp
13b90 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61  rintf()] interfa
13ba0 63 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ces.**          
13bb0 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 70   return either p
13bc0 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
13bd0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
13be0 20 73 74 72 69 6e 67 73 20 68 65 6c 64 20 69 6e   strings held in
13bf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 65  .**           me
13c00 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
13c10 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
13c20 6f 63 28 29 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f  oc()] or NULL po
13c30 69 6e 74 65 72 73 20 69 66 0a 2a 2a 20 20 20 20  inters if.**    
13c40 20 20 20 20 20 20 20 61 20 63 61 6c 6c 20 74 6f         a call to
13c50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13c60 28 29 5d 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  ()] fails..**.**
13c70 20 7b 48 31 37 34 30 36 7d 20 20 54 68 65 20 5b   {H17406}  The [
13c80 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
13c90 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72  ()] interface wr
13ca0 69 74 65 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  ites a zero-term
13cb0 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  inated.**       
13cc0 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67      UTF-8 string
13cd0 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
13ce0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
13cf0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
13d00 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
13d10 20 70 72 6f 76 69 64 65 64 20 74 68 61 74 20 74   provided that t
13d20 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
13d30 65 72 20 69 73 20 67 72 65 61 74 65 72 20 74 68  er is greater th
13d40 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b  an zero..**.** {
13d50 48 31 37 34 30 37 7d 20 20 54 68 65 20 5b 73 71  H17407}  The [sq
13d60 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
13d70 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
13d80 20 6e 6f 74 20 77 72 69 74 65 20 73 6c 6f 74 73   not write slots
13d90 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
13da0 20 69 74 73 20 6f 75 74 70 75 74 20 62 75 66 66   its output buff
13db0 65 72 20 28 74 68 65 20 73 65 63 6f 6e 64 20 70  er (the second p
13dc0 61 72 61 6d 65 74 65 72 29 20 6f 75 74 73 69 64  arameter) outsid
13dd0 65 20 74 68 65 20 72 61 6e 67 65 0a 2a 2a 20 20  e the range.**  
13de0 20 20 20 20 20 20 20 20 20 6f 66 20 30 20 74 68           of 0 th
13df0 72 6f 75 67 68 20 4e 2d 31 20 28 77 68 65 72 65  rough N-1 (where
13e00 20 4e 20 69 73 20 74 68 65 20 66 69 72 73 74 20   N is the first 
13e10 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 20 20  parameter).**   
13e20 20 20 20 20 20 20 20 20 72 65 67 61 72 64 6c 65          regardle
13e30 73 73 20 6f 66 20 74 68 65 20 6c 65 6e 67 74 68  ss of the length
13e40 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 0a 2a   of the string.*
13e50 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 71 75  *           requ
13e60 65 73 74 65 64 20 62 79 20 74 68 65 20 66 6f 72  ested by the for
13e70 6d 61 74 20 73 70 65 63 69 66 69 63 61 74 69 6f  mat specificatio
13e80 6e 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  n..*/.char *sqli
13e90 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
13ea0 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
13eb0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
13ec0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
13ed0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
13ee0 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
13ef0 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
13f00 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
13f10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13f20 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
13f30 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 48 31  on Subsystem {H1
13f40 37 33 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  7300} <S20000>.*
13f50 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
13f60 63 6f 72 65 20 20 75 73 65 73 20 74 68 65 73 65  core  uses these
13f70 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
13f80 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
13f90 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
13fa0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13fb0 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
13fc0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
13fd0 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
13fe0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
13ff0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
14000 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
14010 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
14020 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
14030 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
14040 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
14050 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
14060 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
14070 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
14080 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
14090 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
140a0 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
140b0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
140c0 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
140d0 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
140e0 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69  eter..** If sqli
140f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
14100 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
14110 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
14120 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
14130 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
14140 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20 70  inter.  If the p
14150 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
14160 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
14170 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
14180 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
14190 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
141a0 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
141b0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  inter..**.** Cal
141c0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
141d0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
141e0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
141f0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
14200 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
14210 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14220 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
14230 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
14240 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
14250 65 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69  eused.  The sqli
14260 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
14270 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
14280 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
14290 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
142a0 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
142b0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
142c0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
142d0 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
142e0 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
142f0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
14300 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
14310 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
14320 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
14330 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
14340 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
14350 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
14360 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
14370 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
14380 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
14390 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
143a0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
143b0 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
143c0 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
143d0 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
143e0 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
143f0 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
14400 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
14410 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
14420 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
14430 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
14440 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a 0a 2a  te3_free()..**.*
14450 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
14460 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
14470 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
14480 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
14490 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
144a0 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
144b0 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
144c0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
144d0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
144e0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
144f0 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
14500 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
14510 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  ** parameter.  I
14520 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
14530 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
14540 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
14550 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
14560 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
14570 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
14580 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
14590 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
145a0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
145b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
145c0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
145d0 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73  c()..** If the s
145e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
145f0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
14600 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
14610 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
14620 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
14630 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
14640 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
14650 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
14660 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
14670 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
14680 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
14690 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c()..** sqlite3_
146a0 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
146b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
146c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
146d0 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
146e0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
146f0 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66  e or NULL if suf
14700 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
14710 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
14720 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69  * If M is the si
14730 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
14740 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
14750 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
14760 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
14770 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
14780 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
14790 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
147a0 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
147b0 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
147c0 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
147d0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
147e0 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c  freed..** If sql
147f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
14800 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
14810 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
14820 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
14830 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68   freed..**.** Th
14840 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
14850 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
14860 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
14870 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
14880 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
14890 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
148a0 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8 byte boundary.
148b0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
148c0 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65   default impleme
148d0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d  ntation of the m
148e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
148f0 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 0a   subsystem uses.
14900 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c  ** the malloc(),
14910 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
14920 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62  ree() provided b
14930 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  y the standard C
14940 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31   library..** {H1
14950 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69  7382} However, i
14960 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14970 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
14980 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53   SQLITE_MEMORY_S
14990 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43  IZE=<i>NNN</i> C
149a0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
149b0 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e  cro (where <i>NN
149c0 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69  N</i>.** is an i
149d0 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53 51  nteger), then SQ
149e0 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74  Lite create a st
149f0 61 74 69 63 20 61 72 72 61 79 20 6f 66 20 61 74  atic array of at
14a00 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e   least.** <i>NNN
14a10 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69  </i> bytes in si
14a20 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68 61 74  ze and uses that
14a30 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f   array for all o
14a40 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a  f its dynamic.**
14a50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14a60 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20  on needs. {END} 
14a70 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f   Additional memo
14a80 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74  ry allocator opt
14a90 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61  ions.** may be a
14aa0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
14ab0 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49  eleases..**.** I
14ac0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
14ad0 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
14ae0 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
14af0 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
14b00 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
14b10 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
14b20 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
14b30 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
14b40 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
14b50 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
14b60 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
14b70 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
14b80 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
14b90 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
14ba0 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
14bb0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
14bc0 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
14bd0 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  * The Windows OS
14be0 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
14bf0 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79   calls.** the sy
14c00 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
14c10 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
14c20 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
14c30 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
14c40 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
14c50 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
14c60 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
14c70 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
14c80 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
14c90 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
14ca0 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
14cb0 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
14cc0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14cd0 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65   errors are dete
14ce0 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
14cf0 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62  y are reported b
14d00 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
14d10 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
14d20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
14d30 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
14d40 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
14d50 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
14d60 2a 20 7b 48 31 37 33 30 33 7d 20 20 54 68 65 20  * {H17303}  The 
14d70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14d80 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
14d90 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70  turns either a p
14da0 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ointer to.**    
14db0 20 20 20 20 20 20 20 61 20 6e 65 77 6c 79 20 63         a newly c
14dc0 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b  hecked-out block
14dd0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
14de0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ytes of memory.*
14df0 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74  *           that
14e00 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   is 8-byte align
14e10 65 64 2c 20 6f 72 20 69 74 20 72 65 74 75 72 6e  ed, or it return
14e20 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73 20  s NULL if it is 
14e30 75 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20  unable.**       
14e40 20 20 20 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74      to fulfill t
14e50 68 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a  he request..**.*
14e60 2a 20 7b 48 31 37 33 30 34 7d 20 20 54 68 65 20  * {H17304}  The 
14e70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14e80 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
14e90 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
14ea0 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20 20  nter if.**      
14eb0 20 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20 74       N is less t
14ec0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
14ed0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  zero..**.** {H17
14ee0 33 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  305}  The [sqlit
14ef0 65 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74 65  e3_free(P)] inte
14f00 72 66 61 63 65 20 72 65 6c 65 61 73 65 73 20 6d  rface releases m
14f10 65 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c 79  emory previously
14f20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
14f30 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
14f40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
14f50 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
14f60 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  oc()],.**       
14f70 20 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61 76      making it av
14f80 61 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75 73  ailable for reus
14f90 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 36  e..**.** {H17306
14fa0 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71  }  A call to [sq
14fb0 6c 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29  lite3_free(NULL)
14fc0 5d 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  ] is a harmless 
14fd0 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  no-op..**.** {H1
14fe0 37 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f  7310}  A call to
14ff0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
15000 63 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69 76  c(0,N)] is equiv
15010 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a  alent to a call.
15020 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
15030 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
15040 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  N)]..**.** {H173
15050 31 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b  12}  A call to [
15060 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15070 50 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61 6c  P,0)] is equival
15080 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a  ent to a call.**
15090 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73             to [s
150a0 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 2e  qlite3_free(P)].
150b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 35 7d 20  .**.** {H17315} 
150c0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
150d0 20 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d   uses [sqlite3_m
150e0 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
150f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  e3_realloc()],.*
15100 2a 20 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  *           and 
15110 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
15120 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
15130 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
15140 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  n and.**        
15150 20 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20     deallocation 
15160 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  needs..**.** {H1
15170 37 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c 69  7318}  The [sqli
15180 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29  te3_realloc(P,N)
15190 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
151a0 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69  rns either a poi
151b0 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  nter.**         
151c0 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20    to a block of 
151d0 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f  checked-out memo
151e0 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ry of at least N
151f0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a   bytes in size.*
15200 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74  *           that
15210 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   is 8-byte align
15220 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  ed, or a NULL po
15230 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  inter..**.** {H1
15240 37 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c  7321}  When [sql
15250 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
15260 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  )] returns a non
15270 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69  -NULL pointer, i
15280 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20  t first.**      
15290 20 20 20 20 20 63 6f 70 69 65 73 20 74 68 65 20       copies the 
152a0 66 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f 66  first K bytes of
152b0 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20   content from P 
152c0 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 0a 2a  into the newly.*
152d0 2a 20 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f  *           allo
152e0 63 61 74 65 64 20 62 6c 6f 63 6b 2c 20 77 68 65  cated block, whe
152f0 72 65 20 4b 20 69 73 20 74 68 65 20 6c 65 73 73  re K is the less
15300 65 72 20 6f 66 20 4e 20 61 6e 64 20 74 68 65 20  er of N and the 
15310 73 69 7a 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20  size of.**      
15320 20 20 20 20 20 74 68 65 20 62 75 66 66 65 72 20       the buffer 
15330 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 32  P..**.** {H17322
15340 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  }  When [sqlite3
15350 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
15360 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c  eturns a non-NUL
15370 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69  L pointer, it fi
15380 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rst.**          
15390 20 72 65 6c 65 61 73 65 73 20 74 68 65 20 62 75   releases the bu
153a0 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ffer P..**.** {H
153b0 31 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73 71  17323}  When [sq
153c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
153d0 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  N)] returns NULL
153e0 2c 20 74 68 65 20 62 75 66 66 65 72 20 50 20 69  , the buffer P i
153f0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e  s.**           n
15400 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 72  ot modified or r
15410 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41  eleased..**.** A
15420 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
15430 2a 20 7b 41 31 37 33 35 30 7d 20 20 54 68 65 20  * {A17350}  The 
15440 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
15450 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
15460 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
15470 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
15480 20 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20             must 
15490 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
154a0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
154b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
154c0 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  prior.**        
154d0 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66     invocation of
154e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
154f0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
15500 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
15510 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  have.**         
15520 20 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72    not yet been r
15530 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eleased..**.** {
15540 41 31 37 33 35 31 7d 20 20 54 68 65 20 61 70 70  A17351}  The app
15550 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
15560 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
15570 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 20  any part of.**  
15580 20 20 20 20 20 20 20 20 20 61 20 62 6c 6f 63 6b           a block
15590 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
155a0 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
155b0 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  eased using.**  
155c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
155d0 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
155e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
155f0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
15600 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
15610 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
15620 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
15630 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
15640 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
15650 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
15660 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
15670 74 61 74 69 73 74 69 63 73 20 7b 48 31 37 33 37  tatistics {H1737
15680 30 7d 20 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a  0} <S30210>.**.*
15690 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
156a0 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
156b0 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
156c0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
156d0 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
156e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
156f0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
15700 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
15710 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
15720 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
15730 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
15740 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
15750 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
15760 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
15770 2a 0a 2a 2a 20 7b 48 31 37 33 37 31 7d 20 54 68  *.** {H17371} Th
15780 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
15790 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
157a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
157b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
157c0 20 20 20 20 20 20 20 20 20 20 6f 66 20 6d 65 6d            of mem
157d0 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
157e0 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
157f0 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
15800 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37  d)..**.** {H1737
15810 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
15820 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
15830 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
15840 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
15850 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
15860 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
15870 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
15880 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
15890 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20  r mark.**       
158a0 20 20 20 77 61 73 20 6c 61 73 74 20 72 65 73 65     was last rese
158b0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 34  t..**.** {H17374
158c0 7d 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74  } The values ret
158d0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
158e0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
158f0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
15900 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
15910 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
15920 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
15930 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ad.**          a
15940 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
15950 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
15960 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
15970 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20  _malloc()],.**  
15980 20 20 20 20 20 20 20 20 62 75 74 20 6e 6f 74 20          but not 
15990 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
159a0 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
159b0 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
159c0 61 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ary.**          
159d0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
159e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
159f0 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
15a00 20 7b 48 31 37 33 37 35 7d 20 54 68 65 20 6d 65   {H17375} The me
15a10 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
15a20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
15a30 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
15a40 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ue of.**        
15a50 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72    [sqlite3_memor
15a60 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
15a70 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
15a80 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ameter to.**    
15a90 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
15aa0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
15ab0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 54 68 65  )] is true.  The
15ac0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
15ad0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b  **          by [
15ae0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
15af0 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
15b00 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
15b10 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ark.**          
15b20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
15b30 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
15b40 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
15b50 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
15b60 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
15b70 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
15b80 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
15b90 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
15ba0 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
15bb0 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
15bc0 65 72 61 74 6f 72 20 7b 48 31 37 33 39 30 7d 20  erator {H17390} 
15bd0 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53  <S20000>.**.** S
15be0 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
15bf0 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
15c00 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
15c10 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
15c20 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
15c30 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 52 4f 57  elect random ROW
15c40 49 44 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69  IDs when inserti
15c50 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
15c60 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
15c70 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
15c80 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
15c90 73 69 62 6c 65 20 52 4f 57 49 44 2e 20 20 54 68  sible ROWID.  Th
15ca0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
15cb0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
15cc0 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
15cd0 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
15ce0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
15cf0 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
15d00 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
15d10 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
15d20 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
15d30 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
15d40 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
15d50 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
15d60 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
15d70 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
15d80 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
15d90 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d  ** The first tim
15da0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
15db0 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65  s invoked (eithe
15dc0 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20  r internally or 
15dd0 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  by.** the applic
15de0 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20  ation) the PRNG 
15df0 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  is seeded using 
15e00 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
15e10 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ned.** from the 
15e20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
15e30 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
15e40 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
15e50 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c  object..** On al
15e60 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
15e70 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73  ocations, the ps
15e80 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
15e90 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
15ea0 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
15eb0 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
15ec0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
15ed0 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
15ee0 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a  .** method..**.*
15ef0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
15f00 0a 2a 2a 20 7b 48 31 37 33 39 32 7d 20 54 68 65  .** {H17392} The
15f10 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d   [sqlite3_random
15f20 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e 74 65 72  ness(N,P)] inter
15f30 66 61 63 65 20 77 72 69 74 65 73 20 4e 20 62 79  face writes N by
15f40 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  tes of.**       
15f50 20 20 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20     high-quality 
15f60 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
15f70 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
15f80 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
15f90 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
15fa0 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
15fb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
15fc0 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
15fd0 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
15fe0 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 37 30  ks {H12500} <S70
15ff0 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  100>.**.** This 
16000 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
16010 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63  s a authorizer c
16020 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
16030 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
16040 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16050 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
16060 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
16070 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  nt..** The autho
16080 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
16090 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
160a0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
160b0 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
160c0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
160d0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
160e0 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
160f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
16100 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
16110 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
16120 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
16130 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69  _v2()].  At vari
16140 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
16150 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
16160 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
16170 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
16180 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
16190 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
161a0 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
161b0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
161c0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
161d0 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
161e0 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
161f0 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  .  The authorize
16200 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
16210 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
16220 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
16230 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
16240 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
16250 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
16260 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
16270 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
16280 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
16290 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
162a0 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
162b0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
162c0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
162d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
162e0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
162f0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
16300 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
16310 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
16320 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
16330 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
16340 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
16350 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
16360 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
16370 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
16380 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
16390 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
163a0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
163b0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
163c0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
163d0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
163e0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
163f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
16400 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
16410 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
16420 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
16430 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65  sted is ok.  Whe
16440 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
16450 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
16460 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
16470 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
16480 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
16490 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
164a0 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
164b0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
164c0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
164d0 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
164e0 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
164f0 73 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49 66  s is denied.  If
16500 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
16510 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
16520 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
16530 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
16540 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
16550 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
16560 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
16570 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
16580 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
16590 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
165a0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
165b0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
165c0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
165d0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
165e0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
165f0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
16600 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
16610 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
16620 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
16630 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
16640 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
16650 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
16660 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
16670 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  table..**.** The
16680 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
16690 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
166a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
166b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
166c0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
166d0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
166e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
166f0 69 6e 74 65 72 66 61 63 65 2e 20 54 68 65 20 73  interface. The s
16700 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
16710 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
16720 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
16730 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
16740 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
16750 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
16760 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
16770 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
16780 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72 64  rized. The third
16790 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
167a0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
167b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
167c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
167d0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
167e0 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
167f0 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
16800 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
16810 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
16820 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
16830 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
16840 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16850 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
16860 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
16870 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
16880 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
16890 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
168a0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
168b0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
168c0 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
168d0 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
168e0 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
168f0 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
16900 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
16910 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
16920 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
16930 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
16940 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
16950 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
16960 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
16970 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
16980 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
16990 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
169a0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
169b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
169c0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
169d0 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
169e0 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
169f0 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
16a00 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
16a10 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
16a20 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
16a30 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
16a40 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
16a50 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
16a60 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
16a70 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
16a80 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
16a90 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
16aa0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
16ab0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
16ac0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
16ad0 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
16ae0 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
16af0 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
16b00 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
16b10 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
16b20 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
16b30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
16b40 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
16b50 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
16b60 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
16b70 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
16b80 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
16b90 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
16ba0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
16bb0 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67  *.** Only a sing
16bc0 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
16bd0 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
16be0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
16bf0 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
16c00 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
16c10 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
16c20 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
16c30 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
16c40 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61 62  ous call.  Disab
16c50 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
16c60 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
16c70 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
16c80 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
16c90 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
16ca0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
16cb0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61   Note that the a
16cc0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16cd0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
16ce0 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
16cf0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
16d00 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
16d10 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
16d20 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
16d30 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
16d40 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
16d50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
16d60 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  p()]..**.** INVA
16d70 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
16d80 31 32 35 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  12501} The [sqli
16d90 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
16da0 65 72 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  er(D,...)] inter
16db0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
16dc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74  .**          aut
16dd0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
16de0 20 77 69 74 68 20 64 61 74 61 62 61 73 65 20 63   with database c
16df0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a  onnection D..**.
16e00 2a 2a 20 7b 48 31 32 35 30 32 7d 20 54 68 65 20  ** {H12502} The 
16e10 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16e20 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
16e30 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
16e40 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   are.**         
16e50 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 2e   being compiled.
16e60 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 33 7d 20  .**.** {H12503} 
16e70 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
16e80 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
16e90 6e 73 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ns any value oth
16ea0 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
16eb0 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f      [SQLITE_IGNO
16ec0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
16ed0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
16ee0 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  Y], then.**     
16ef0 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
16f00 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
16f10 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
16f20 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ll that caused.*
16f30 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
16f40 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16f50 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20  ck to run shall 
16f60 66 61 69 6c 20 77 69 74 68 20 61 6e 0a 2a 2a 20  fail with an.** 
16f70 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
16f80 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f  _ERROR] error co
16f90 64 65 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70  de and an approp
16fa0 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73  riate error mess
16fb0 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  age..**.** {H125
16fc0 30 34 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74  04} When the aut
16fd0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
16fe0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
16ff0 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65 72 61 74  _OK], the operat
17000 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
17010 64 65 73 63 72 69 62 65 64 20 69 73 20 70 72 6f  described is pro
17020 63 65 73 73 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e  cessed normally.
17030 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 35 7d 20  .**.** {H12505} 
17040 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69  When the authori
17050 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
17060 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
17070 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  Y], the.**      
17080 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
17090 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
170a0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
170b0 61 74 20 63 61 75 73 65 64 20 74 68 65 0a 2a 2a  at caused the.**
170c0 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f 72            author
170d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f  izer callback to
170e0 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 0a   run shall fail.
170f0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68  **          with
17100 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   an [SQLITE_ERRO
17110 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  R] error code an
17120 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  d an error messa
17130 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  ge.**          e
17140 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 20 61  xplaining that a
17150 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
17160 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 36 7d 20  .**.** {H12506} 
17170 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
17180 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20  r code (the 2nd 
17190 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
171a0 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20   authorizer.**  
171b0 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
171c0 29 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  ) is [SQLITE_REA
171d0 44 5d 20 61 6e 64 20 74 68 65 20 61 75 74 68 6f  D] and the autho
171e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
171f0 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
17200 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52     [SQLITE_IGNOR
17210 45 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 72 65  E], then the pre
17220 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
17230 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
17240 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  o.**          in
17250 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75  sert a NULL valu
17260 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
17270 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
17280 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
17290 2a 20 20 20 20 20 20 20 20 20 20 62 65 65 6e 20  *          been 
172a0 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
172b0 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
172c0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  urned..**.** {H1
172d0 32 35 30 37 7d 20 49 66 20 74 68 65 20 61 75 74  2507} If the aut
172e0 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68  horizer code (th
172f0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
17300 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
17310 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  r.**          ca
17320 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e 79 74 68  llback) is anyth
17330 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
17340 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c 20 74 68  SQLITE_READ], th
17350 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  en.**          a
17360 20 72 65 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49   return of [SQLI
17370 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61 73 20 74  TE_IGNORE] has t
17380 68 65 20 73 61 6d 65 20 65 66 66 65 63 74 20 61  he same effect a
17390 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e  s [SQLITE_DENY].
173a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 30 7d 20  .**.** {H12510} 
173b0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
173c0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
173d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
173e0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20  s a copy of.**  
173f0 20 20 20 20 20 20 20 20 74 68 65 20 74 68 69 72          the thir
17400 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
17410 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
17420 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
17430 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b  terface..**.** {
17440 48 31 32 35 31 31 7d 20 54 68 65 20 73 65 63 6f  H12511} The seco
17450 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
17460 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
17470 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20  an integer.**   
17480 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43         [SQLITE_C
17490 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
174a0 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
174b0 73 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  s the particular
174c0 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20   action.**      
174d0 20 20 20 20 74 6f 20 62 65 20 61 75 74 68 6f 72      to be author
174e0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ized..**.** {H12
174f0 35 31 32 7d 20 54 68 65 20 74 68 69 72 64 20 74  512} The third t
17500 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
17510 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 63  ameters to the c
17520 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20  allback are.**  
17530 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
17540 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
17550 74 68 61 74 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20  that contain.** 
17560 20 20 20 20 20 20 20 20 20 61 64 64 69 74 69 6f           additio
17570 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75  nal details abou
17580 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
17590 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
175a0 2a 0a 2a 2a 20 7b 48 31 32 35 32 30 7d 20 45 61  *.** {H12520} Ea
175b0 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
175c0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
175d0 65 72 28 29 5d 20 6f 76 65 72 72 69 64 65 73 0a  er()] overrides.
175e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 79 20  **          any 
175f0 70 72 65 76 69 6f 75 73 6c 79 20 69 6e 73 74 61  previously insta
17600 6c 6c 65 64 20 61 75 74 68 6f 72 69 7a 65 72 2e  lled authorizer.
17610 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 31 7d 20  .**.** {H12521} 
17620 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65  A NULL authorize
17630 72 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20  r means that no 
17640 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
17650 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
17660 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ck is invoked..*
17670 2a 0a 2a 2a 20 7b 48 31 32 35 32 32 7d 20 54 68  *.** {H12522} Th
17680 65 20 64 65 66 61 75 6c 74 20 61 75 74 68 6f 72  e default author
17690 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f  izer is NULL..*/
176a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
176b0 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
176c0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
176d0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
176e0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
176f0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
17700 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
17710 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
17720 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
17730 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
17740 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
17750 73 20 7b 48 31 32 35 39 30 7d 20 3c 48 31 32 35  s {H12590} <H125
17760 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  00>.**.** The [s
17770 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17780 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
17790 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
177a0 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
177b0 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
177c0 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
177d0 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
177e0 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
177f0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
17800 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
17810 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
17820 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
17830 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
17840 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
17850 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
17860 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
17870 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
17880 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65  ormation..*/.#de
17890 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
178a0 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
178b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
178c0 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
178d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
178e0 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
178f0 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
17900 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
17910 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
17920 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
17930 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
17940 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b 48 31 32  ction Codes {H12
17950 35 35 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a  550} <H12500>.**
17960 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
17970 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
17980 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
17990 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
179a0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
179b0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
179c0 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
179d0 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
179e0 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
179f0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
17a00 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
17a10 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
17a20 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
17a30 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
17a40 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
17a50 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
17a60 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
17a70 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
17a80 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
17a90 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
17aa0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
17ab0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
17ac0 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
17ad0 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
17ae0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
17af0 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
17b00 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
17b10 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
17b20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
17b30 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
17b40 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
17b50 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
17b60 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
17b70 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
17b80 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
17b90 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
17ba0 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74  rameter.  The 5t
17bb0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
17bc0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
17bd0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
17be0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
17bf0 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
17c00 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
17c10 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20  if applicable.  
17c20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
17c30 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
17c40 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
17c50 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
17c60 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
17c70 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
17c80 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
17c90 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
17ca0 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
17cb0 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
17cc0 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
17cd0 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
17ce0 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
17cf0 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
17d00 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  NTS:.**.** {H125
17d10 35 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70  51} The second p
17d20 61 72 61 6d 65 74 65 72 20 74 6f 20 61 6e 0a 2a  arameter to an.*
17d30 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
17d40 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
17d50 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
17d60 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 61 6c 77  callback] is alw
17d70 61 79 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a  ays an integer.*
17d80 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
17d90 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72  TE_COPY | author
17da0 69 7a 65 72 20 63 6f 64 65 5d 20 74 68 61 74 20  izer code] that 
17db0 73 70 65 63 69 66 69 65 73 20 77 68 61 74 20 61  specifies what a
17dc0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
17dd0 20 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f    is being autho
17de0 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  rized..**.** {H1
17df0 32 35 35 32 7d 20 54 68 65 20 33 72 64 20 61 6e  2552} The 3rd an
17e00 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
17e10 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
17e20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
17e30 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
17e40 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c  thorization call
17e50 62 61 63 6b 5d 0a 2a 2a 20 20 20 20 20 20 20 20  back].**        
17e60 20 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65    will be parame
17e70 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
17e80 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 0a  ending on which.
17e90 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
17ea0 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f  ITE_COPY | autho
17eb0 72 69 7a 65 72 20 63 6f 64 65 5d 20 69 73 20 75  rizer code] is u
17ec0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
17ed0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
17ee0 2a 2a 20 7b 48 31 32 35 35 33 7d 20 54 68 65 20  ** {H12553} The 
17ef0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
17f00 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
17f10 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
17f20 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
17f30 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20  rizer callback] 
17f40 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20  is the name.**  
17f50 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 64          of the d
17f60 61 74 61 62 61 73 65 20 28 65 78 61 6d 70 6c 65  atabase (example
17f70 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22  : "main", "temp"
17f80 2c 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  , etc.) if appli
17f90 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  cable..**.** {H1
17fa0 32 35 35 34 7d 20 54 68 65 20 36 74 68 20 70 61  2554} The 6th pa
17fb0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
17fc0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
17fd0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
17fe0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
17ff0 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68 65  callback] is the
18000 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   name.**        
18010 20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d    of the inner-m
18020 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
18030 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
18040 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 20  onsible for.**  
18050 20 20 20 20 20 20 20 20 74 68 65 20 61 63 63 65          the acce
18060 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
18070 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
18080 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
18090 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 20 20  ectly from.**   
180a0 20 20 20 20 20 20 20 74 6f 70 2d 6c 65 76 65 6c         top-level
180b0 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
180c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
180d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
180e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
180f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
18100 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
18110 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
18120 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
18130 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
18140 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
18150 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
18160 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18170 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
18180 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
18190 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
181a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
181b0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
181c0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
181d0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
181e0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
181f0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
18200 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18210 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
18220 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18230 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18240 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18250 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
18260 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
18270 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
18280 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
18290 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
182a0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
182b0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
182c0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
182d0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
182e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
182f0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
18300 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
18310 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
18320 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
18330 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18340 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
18350 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
18360 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
18370 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18380 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18390 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
183a0 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
183b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
183c0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
183d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
183e0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
183f0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
18400 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
18410 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18420 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18430 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
18440 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
18450 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
18460 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18470 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18480 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
18490 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
184a0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
184b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
184c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
184d0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
184e0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
184f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
18500 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18510 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18520 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
18530 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
18540 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
18550 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18560 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
18570 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
18580 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
18590 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
185a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
185b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
185c0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
185d0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
185e0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
185f0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
18600 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
18610 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
18620 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
18630 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
18640 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18650 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
18660 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
18670 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
18680 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18690 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
186a0 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
186b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
186c0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
186d0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
186e0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
186f0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
18700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
18710 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18720 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
18730 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
18740 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
18750 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
18760 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
18770 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18780 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18790 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
187a0 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
187b0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
187c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
187d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
187e0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
187f0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
18800 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
18810 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
18820 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18830 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
18840 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
18850 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
18860 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18870 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18880 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
18890 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
188a0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
188b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
188c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
188d0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
188e0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
188f0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
18900 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18910 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18920 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
18930 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
18940 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
18950 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18960 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18970 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
18980 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
18990 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
189a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
189b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
189c0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
189d0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
189e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
189f0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
18a00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18a10 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
18a20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
18a30 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
18a40 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
18a50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
18a60 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
18a70 20 20 20 33 31 20 20 20 2f 2a 20 46 75 6e 63 74     31   /* Funct
18a80 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ion Name   NULL 
18a90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18aa0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
18ab0 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
18ac0 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
18ad0 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  ger used */../*.
18ae0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
18af0 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
18b00 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31  ng Functions {H1
18b10 32 32 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2280} <S60400>.*
18b20 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
18b30 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
18b40 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
18b50 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
18b60 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
18b70 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
18b80 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
18b90 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
18ba0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
18bb0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
18bc0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
18bd0 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
18be0 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
18bf0 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
18c00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
18c10 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
18c20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
18c30 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
18c40 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20  returns a UTF-8 
18c50 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
18c60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
18c70 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74  ext.** as the st
18c80 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
18c90 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20  gins executing. 
18ca0 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c   Additional call
18cb0 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61  backs occur.** a
18cc0 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
18cd0 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
18ce0 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
18cf0 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
18d00 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
18d10 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
18d20 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
18d30 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a  es the trigger..
18d40 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
18d50 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
18d60 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
18d70 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
18d80 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
18d90 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
18da0 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70  finishes.  The p
18db0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
18dc0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
18dd0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
18de0 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
18df0 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
18e00 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
18e10 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
18e20 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
18e30 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   run..**.** The 
18e40 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
18e50 29 20 41 50 49 20 69 73 20 63 75 72 72 65 6e 74  ) API is current
18e60 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  ly considered ex
18e70 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a  perimental and.*
18e80 2a 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  * is subject to 
18e90 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61  change or remova
18ea0 6c 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  l in a future re
18eb0 6c 65 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  lease..**.** The
18ec0 20 74 72 69 67 67 65 72 20 72 65 70 6f 72 74 69   trigger reporti
18ed0 6e 67 20 66 65 61 74 75 72 65 20 6f 66 20 74 68  ng feature of th
18ee0 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
18ef0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a   is considered.*
18f00 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  * experimental a
18f10 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f  nd is subject to
18f20 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76   change or remov
18f30 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  al in future rel
18f40 65 61 73 65 73 2e 0a 2a 2a 20 46 75 74 75 72 65  eases..** Future
18f50 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
18f60 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
18f70 64 64 20 6e 65 77 20 74 72 61 63 65 20 63 61 6c  dd new trace cal
18f80 6c 62 61 63 6b 0a 2a 2a 20 69 6e 76 6f 63 61 74  lback.** invocat
18f90 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ions..**.** INVA
18fa0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
18fb0 31 32 32 38 31 7d 20 54 68 65 20 63 61 6c 6c 62  12281} The callb
18fc0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
18fd0 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69  istered by [sqli
18fe0 74 65 33 5f 74 72 61 63 65 28 29 5d 20 69 73 0a  te3_trace()] is.
18ff0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
19000 65 76 65 72 20 61 6e 20 53 51 4c 20 73 74 61 74  ever an SQL stat
19010 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
19020 6e 73 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e  ns to execute an
19030 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  d.**          wh
19040 65 6e 65 76 65 72 20 61 20 74 72 69 67 67 65 72  enever a trigger
19050 20 73 75 62 70 72 6f 67 72 61 6d 20 66 69 72 73   subprogram firs
19060 74 20 62 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e  t begins to run.
19070 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 32 7d 20  .**.** {H12282} 
19080 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
19090 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 6f  lite3_trace()] o
190a0 76 65 72 72 69 64 65 73 20 74 68 65 20 70 72 65  verrides the pre
190b0 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20  viously.**      
190c0 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74      registered t
190d0 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  race callback..*
190e0 2a 0a 2a 2a 20 7b 48 31 32 32 38 33 7d 20 41 20  *.** {H12283} A 
190f0 4e 55 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c 62  NULL trace callb
19100 61 63 6b 20 64 69 73 61 62 6c 65 73 20 74 72 61  ack disables tra
19110 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  cing..**.** {H12
19120 32 38 34 7d 20 54 68 65 20 66 69 72 73 74 20 61  284} The first a
19130 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74  rgument to the t
19140 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
19150 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20   a copy of.**   
19160 20 20 20 20 20 20 20 74 68 65 20 70 6f 69 6e 74         the point
19170 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
19180 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
19190 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
191a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  )]..**.** {H1228
191b0 35 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  5} The second ar
191c0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72  gument to the tr
191d0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ace callback is 
191e0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  a.**          ze
191f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
19200 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  F-8 string conta
19210 69 6e 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e  ining the origin
19220 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20 20 20 20  al text.**      
19230 20 20 20 20 6f 66 20 74 68 65 20 53 51 4c 20 73      of the SQL s
19240 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77  tatement as it w
19250 61 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 5b  as passed into [
19260 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
19270 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  v2()].**        
19280 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c    or the equival
19290 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63  ent, or an SQL c
192a0 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61 74 69 6e  omment indicatin
192b0 67 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a  g the beginning.
192c0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61  **          of a
192d0 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67   trigger subprog
192e0 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ram..**.** {H122
192f0 38 37 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  87} The callback
19300 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
19310 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ered by [sqlite3
19320 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69 73 20 69  _profile()] is i
19330 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20  nvoked.**       
19340 20 20 20 61 73 20 65 61 63 68 20 53 51 4c 20 73     as each SQL s
19350 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
19360 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 38  s..**.** {H12288
19370 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
19380 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f  meter to the pro
19390 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  file callback is
193a0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20   a copy of.**   
193b0 20 20 20 20 20 20 20 74 68 65 20 33 72 64 20 70         the 3rd p
193c0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
193d0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e  ite3_profile()].
193e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 39 7d 20  .**.** {H12289} 
193f0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19400 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66  eter to the prof
19410 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ile callback is 
19420 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  a.**          ze
19430 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
19440 46 2d 38 20 73 74 72 69 6e 67 20 74 68 61 74 20  F-8 string that 
19450 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 63 6f 6d  contains the com
19460 70 6c 65 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a  plete text of.**
19470 20 20 20 20 20 20 20 20 20 20 74 68 65 20 53 51            the SQ
19480 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69  L statement as i
19490 74 20 77 61 73 20 70 72 6f 63 65 73 73 65 64 20  t was processed 
194a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
194b0 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20  are_v2()].**    
194c0 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75        or the equ
194d0 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b  ivalent..**.** {
194e0 48 31 32 32 39 30 7d 20 54 68 65 20 74 68 69 72  H12290} The thir
194f0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
19500 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
19510 61 63 6b 20 69 73 20 61 6e 20 65 73 74 69 6d 61  ack is an estima
19520 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  te.**          o
19530 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
19540 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77  nanoseconds of w
19550 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72  all-clock time r
19560 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20  equired to.**   
19570 20 20 20 20 20 20 20 72 75 6e 20 74 68 65 20 53         run the S
19580 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 72 6f  QL statement fro
19590 6d 20 73 74 61 72 74 20 74 6f 20 66 69 6e 69 73  m start to finis
195a0 68 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  h..*/.void *sqli
195b0 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
195c0 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
195d0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
195e0 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  ar*), void*);.vo
195f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
19600 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
19610 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
19620 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
19630 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
19640 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
19650 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
19660 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
19670 62 61 63 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c  backs {H12910} <
19680 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60400>.**.** Th
19690 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69  is routine confi
196a0 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b  gures a callback
196b0 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a   function - the.
196c0 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  ** progress call
196d0 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69  back - that is i
196e0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
196f0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a  lly during long.
19700 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ** running calls
19710 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
19720 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
19730 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  tep()] and.** [s
19740 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
19750 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ()].  An example
19760 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
19770 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
19780 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
19790 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
197a0 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
197b0 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
197c0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
197d0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
197e0 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
197f0 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
19800 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
19810 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
19820 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
19830 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
19840 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
19850 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
19860 2a 0a 2a 2a 20 7b 48 31 32 39 31 31 7d 20 54 68  *.** {H12911} Th
19870 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
19880 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
19890 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  y sqlite3_progre
198a0 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20  ss_handler().** 
198b0 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f           is invo
198c0 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
198d0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
198e0 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
198f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
19900 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
19910 2a 20 7b 48 31 32 39 31 32 7d 20 54 68 65 20 70  * {H12912} The p
19920 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
19930 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
19940 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69 72   for every N vir
19950 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  tual.**         
19960 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65 73   machine opcodes
19970 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
19980 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
19990 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
199a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  the [sqlite3_pro
199b0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d  gress_handler()]
199c0 20 63 61 6c 6c 20 74 68 61 74 20 72 65 67 69 73   call that regis
199d0 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  tered.**        
199e0 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20    the callback. 
199f0 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68   If N is less th
19a00 61 6e 20 31 2c 20 73 71 6c 69 74 65 33 5f 70 72  an 1, sqlite3_pr
19a10 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
19a20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 63 74  .**          act
19a30 73 20 61 73 20 69 66 20 61 20 4e 55 4c 4c 20 70  s as if a NULL p
19a40 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
19a50 68 61 64 20 62 65 65 6e 20 73 70 65 63 69 66 69  had been specifi
19a60 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  ed..**.** {H1291
19a70 33 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  3} The progress 
19a80 63 61 6c 6c 62 61 63 6b 20 69 74 73 65 6c 66 20  callback itself 
19a90 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  is identified by
19aa0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 20 20   the third.**   
19ab0 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20         argument 
19ac0 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  to sqlite3_progr
19ad0 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 2e 0a 2a  ess_handler()..*
19ae0 2a 0a 2a 2a 20 7b 48 31 32 39 31 34 7d 20 54 68  *.** {H12914} Th
19af0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
19b00 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f  t to sqlite3_pro
19b10 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 20  gress_handler() 
19b20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
19b30 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 61   void pointer pa
19b40 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f 67  ssed to the prog
19b50 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  ress callback.**
19b60 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
19b70 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 69 74 20  on each time it 
19b80 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
19b90 2a 20 7b 48 31 32 39 31 35 7d 20 49 66 20 61 20  * {H12915} If a 
19ba0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
19bb0 5f 73 74 65 70 28 29 5d 20 72 65 73 75 6c 74 73  _step()] results
19bc0 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e 20 4e   in fewer than N
19bd0 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 20 20 20 20   opcodes.**     
19be0 20 20 20 20 20 62 65 69 6e 67 20 65 78 65 63 75       being execu
19bf0 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 70 72  ted, then the pr
19c00 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
19c10 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64  is never invoked
19c20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 36 7d  ..**.** {H12916}
19c30 20 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b   Every call to [
19c40 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
19c50 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20  _handler()].**  
19c60 20 20 20 20 20 20 20 20 6f 76 65 72 77 72 69 74          overwrit
19c70 65 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  es any previousl
19c80 79 20 72 65 67 69 73 74 65 72 65 64 20 70 72 6f  y registered pro
19c90 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
19ca0 2a 0a 2a 2a 20 7b 48 31 32 39 31 37 7d 20 49 66  *.** {H12917} If
19cb0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
19cc0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
19cd0 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70  s NULL then no p
19ce0 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20 20 20 20  rogress.**      
19cf0 20 20 20 20 68 61 6e 64 6c 65 72 20 69 73 20 69      handler is i
19d00 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nvoked..**.** {H
19d10 31 32 39 31 38 7d 20 49 66 20 74 68 65 20 70 72  12918} If the pr
19d20 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
19d30 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
19d40 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20 74   other than 0, t
19d50 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
19d60 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
19d70 61 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e  a if [sqlite3_in
19d80 74 65 72 72 75 70 74 28 29 5d 20 68 61 64 20 62  terrupt()] had b
19d90 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 20 20  een called..**  
19da0 20 20 20 20 20 20 20 20 3c 53 33 30 35 30 30 3e          <S30500>
19db0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
19dc0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
19dd0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
19de0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
19df0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
19e00 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
19e10 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
19e20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37  Connection {H127
19e30 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a  00} <S40200>.**.
19e40 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
19e50 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
19e60 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
19e70 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76  hose name is giv
19e80 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c  en by the.** fil
19e90 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
19ea0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
19eb0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
19ec0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
19ed0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
19ee0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
19ef0 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
19f00 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
19f10 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
19f20 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
19f30 6f 70 65 6e 31 36 28 29 2e 20 41 20 5b 64 61 74  open16(). A [dat
19f40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19f50 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
19f60 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lly.** returned 
19f70 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69  in *ppDb, even i
19f80 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
19f90 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
19fa0 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a  eption is that.*
19fb0 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  * if SQLite is u
19fc0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
19fd0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
19fe0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
19ff0 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c  bject,.** a NULL
1a000 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e   will be written
1a010 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
1a020 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
1a030 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1a040 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20  ].** object. If 
1a050 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
1a060 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
1a070 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
1a080 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
1a090 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
1a0a0 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
1a0b0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
1a0c0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
1a0d0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
1a0e0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
1a0f0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1a100 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
1a110 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
1a120 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
1a130 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
1a140 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
1a150 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ..**.** The defa
1a160 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
1a170 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69   the database wi
1a180 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a  ll be UTF-8 if.*
1a190 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1a1a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
1a1b0 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
1a1c0 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
1a1d0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1a1e0 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65   order if sqlite
1a1f0 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73  3_open16() is us
1a200 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  ed..**.** Whethe
1a210 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
1a220 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
1a230 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
1a240 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
1a250 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
1a260 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a270 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
1a280 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
1a290 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
1a2a0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
1a2b0 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
1a2c0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
1a2d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1a2e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
1a2f0 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
1a300 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
1a310 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
1a320 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
1a330 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
1a340 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
1a350 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
1a360 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
1a370 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a380 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 61 72  .  The flags par
1a390 61 6d 65 74 65 72 20 63 61 6e 20 74 61 6b 65 20  ameter can take 
1a3a0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
1a3b0 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
1a3c0 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
1a3d0 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
1a3e0 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
1a3f0 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
1a400 67 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  g:.**.** <dl>.**
1a410 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
1a420 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
1a430 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1a440 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
1a450 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
1a460 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
1a470 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
1a480 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
1a490 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1a4a0 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
1a4b0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1a4c0 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
1a4d0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1a4e0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
1a4f0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
1a500 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
1a510 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
1a520 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
1a530 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
1a540 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
1a550 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
1a560 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
1a570 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
1a580 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
1a590 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
1a5a0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1a5b0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1a5c0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1a5d0 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
1a5e0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
1a5f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1a600 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1a610 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
1a620 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
1a630 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69 66  is creates it if
1a640 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
1a650 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
1a660 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
1a670 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
1a680 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
1a690 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1a6a0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
1a6b0 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  ().</dd>.** </dl
1a6c0 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
1a6d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
1a6e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1a6f0 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
1a700 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
1a710 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
1a720 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  or one of the co
1a730 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
1a740 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a   above combined.
1a750 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
1a760 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1a770 5d 20 66 6c 61 67 2c 20 74 68 65 6e 20 74 68 65  ] flag, then the
1a780 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
1a790 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
1a7a0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1a7b0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
1a7c0 69 73 20 73 65 74 2c 20 74 68 65 6e 20 6d 75 74  is set, then mut
1a7d0 65 78 65 73 20 6f 6e 20 74 68 65 0a 2a 2a 20 6f  exes on the.** o
1a7e0 70 65 6e 65 64 20 5b 64 61 74 61 62 61 73 65 20  pened [database 
1a7f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 72 65 20  connection] are 
1a800 64 69 73 61 62 6c 65 64 20 61 6e 64 20 74 68 65  disabled and the
1a810 20 61 70 70 6c 69 61 74 69 6f 6e 20 6d 75 73 74   appliation must
1a820 0a 2a 2a 20 69 6e 73 75 72 65 20 74 68 61 74 20  .** insure that 
1a830 61 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b 64  access to the [d
1a840 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a850 6f 6e 5d 20 61 6e 64 20 69 74 73 20 61 73 73 6f  on] and its asso
1a860 63 69 61 74 65 64 0a 2a 2a 20 5b 70 72 65 70 61  ciated.** [prepa
1a870 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
1a880 69 73 20 73 65 72 69 61 6c 69 7a 65 64 2e 20 20  is serialized.  
1a890 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
1a8a0 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 0a 2a  _NOMUTEX] flag.*
1a8b0 2a 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74  * is the default
1a8c0 20 62 65 68 61 76 69 6f 72 20 69 73 20 53 51 4c   behavior is SQL
1a8d0 69 74 65 20 69 73 20 63 6f 6e 66 69 67 75 72 65  ite is configure
1a8e0 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
1a8f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
1a900 4c 54 49 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  LTITHREAD] or [S
1a910 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
1a920 47 4c 45 54 48 52 45 41 44 5d 20 6f 70 74 69 6f  GLETHREAD] optio
1a930 6e 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ns.** to [sqlite
1a940 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 20 20 54 68  3_config()].  Th
1a950 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
1a960 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 6f 6e 6c  OMUTEX] flag onl
1a970 79 20 6d 61 6b 65 73 20 61 0a 2a 2a 20 64 69 66  y makes a.** dif
1a980 66 65 72 65 6e 63 65 20 77 68 65 6e 20 53 51 4c  ference when SQL
1a990 69 74 65 20 69 73 20 69 6e 20 69 74 73 20 64 65  ite is in its de
1a9a0 66 61 75 6c 74 20 5b 53 51 4c 49 54 45 5f 43 4f  fault [SQLITE_CO
1a9b0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
1a9c0 20 6d 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20   mode..**.** If 
1a9d0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1a9e0 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
1a9f0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
1aa00 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
1aa10 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
1aa20 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
1aa30 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73  onnection.  This
1aa40 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1aa50 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
1aa60 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
1aa70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1aa80 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
1aa90 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1aaa0 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
1aab0 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
1aac0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
1aad0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
1aae0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
1aaf0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
1ab00 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1ab10 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
1ab20 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
1ab30 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
1ab40 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
1ab50 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
1ab60 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
1ab70 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
1ab80 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
1ab90 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
1aba0 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
1abb0 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  ** If the filena
1abc0 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
1abd0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
1abe0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
1abf0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
1ac00 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
1ac10 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 76  ated.  This priv
1ac20 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
1ac30 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
1ac40 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
1ac50 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
1ac60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ac70 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
1ac80 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
1ac90 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1aca0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
1acb0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
1acc0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
1acd0 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
1ace0 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
1acf0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1ad00 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
1ad10 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1ad20 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
1ad30 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72 74  e.  If the fourt
1ad40 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
1ad50 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1ad60 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
1ad70 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1ad80 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
1ad90 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
1ada0 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
1adb0 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
1adc0 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
1add0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1ade0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
1adf0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1ae00 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
1ae10 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
1ae20 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
1ae30 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
1ae40 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
1ae50 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
1ae60 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
1ae70 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
1ae80 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
1ae90 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
1aea0 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
1aeb0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
1aec0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
1aed0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
1aee0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1aef0 2a 20 7b 48 31 32 37 30 31 7d 20 54 68 65 20 5b  * {H12701} The [
1af00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1af10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1af20 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ()], and.**     
1af30 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
1af40 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
1af50 63 65 73 20 63 72 65 61 74 65 20 61 20 6e 65 77  ces create a new
1af60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
1af70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1af80 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  n] associated wi
1af90 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
1afa0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
1afb0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 69 72 20   given in their 
1afc0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1afd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 32 7d 20  .**.** {H12702} 
1afe0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
1aff0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
1b000 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a  eted as UTF-8.**
1b010 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 5b 73            for [s
1b020 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61  qlite3_open()] a
1b030 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
1b040 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54  _v2()] and as UT
1b050 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20  F-16.**         
1b060 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1b070 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73  yte order for [s
1b080 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1b090 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 33 7d  ..**.** {H12703}
1b0a0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
1b0b0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
1b0c0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1b0d0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1b0e0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
1b0f0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1b100 32 28 29 5d 20 77 72 69 74 65 73 20 61 20 70 6f  2()] writes a po
1b110 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a  inter to a new.*
1b120 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
1b130 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b140 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a   into *ppDb..**.
1b150 2a 2a 20 7b 48 31 32 37 30 34 7d 20 54 68 65 20  ** {H12704} The 
1b160 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1b170 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1b180 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20  6()], and.**    
1b190 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
1b1a0 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
1b1b0 61 63 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  aces return [SQL
1b1c0 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63  ITE_OK] upon suc
1b1d0 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20  cess,.**        
1b1e0 20 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69    or an appropri
1b1f0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
1b200 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a   on failure..**.
1b210 2a 2a 20 7b 48 31 32 37 30 36 7d 20 54 68 65 20  ** {H12706} The 
1b220 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63  default text enc
1b230 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20  oding for a new 
1b240 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64  database created
1b250 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
1b260 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
1b270 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1b280 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20  open_v2()] will 
1b290 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  be UTF-8..**.** 
1b2a0 7b 48 31 32 37 30 37 7d 20 54 68 65 20 64 65 66  {H12707} The def
1b2b0 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69  ault text encodi
1b2c0 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74  ng for a new dat
1b2d0 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73  abase created us
1b2e0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
1b2f0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
1b300 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  )] will be UTF-1
1b310 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 39  6..**.** {H12709
1b320 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  } The [sqlite3_o
1b330 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72 66  pen(F,D)] interf
1b340 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ace is equivalen
1b350 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  t to.**         
1b360 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1b370 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72  2(F,D,G,0)] wher
1b380 65 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  e the G paramete
1b390 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  r is.**         
1b3a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
1b3b0 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45  ADWRITE]|[SQLITE
1b3c0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a  _OPEN_CREATE]..*
1b3d0 2a 0a 2a 2a 20 7b 48 31 32 37 31 31 7d 20 49 66  *.** {H12711} If
1b3e0 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
1b3f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
1b400 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63  n_v2(F,D,G,V)] c
1b410 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20  ontains the.**  
1b420 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
1b430 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
1b440 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68  EADONLY] then th
1b450 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1b460 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ened.**         
1b470 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c   for reading onl
1b480 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 32  y..**.** {H12712
1b490 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
1b4a0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1b4b0 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56  _open_v2(F,D,G,V
1b4c0 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a  )] contains the.
1b4d0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
1b4e0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
1b4f0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 74 68  EN_READWRITE] th
1b500 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1b510 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20  is opened.**    
1b520 20 20 20 20 20 20 72 65 61 64 69 6e 67 20 61 6e        reading an
1b530 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
1b540 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65  sible, or for re
1b550 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68  ading only if th
1b560 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  e.**          fi
1b570 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
1b580 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
1b590 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a  rating system..*
1b5a0 2a 0a 2a 2a 20 7b 48 31 32 37 31 33 7d 20 49 66  *.** {H12713} If
1b5b0 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
1b5c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
1b5d0 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f  n(v2(F,D,G,V)] o
1b5e0 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  mits the.**     
1b5f0 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
1b600 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1b610 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61  TE] and the data
1b620 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1b630 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f            previo
1b640 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65  usly exist, an e
1b650 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1b660 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 34 7d  ..**.** {H12714}
1b670 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
1b680 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1b690 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29  open(v2(F,D,G,V)
1b6a0 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a  ] contains the.*
1b6b0 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76  *          bit v
1b6c0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  alue [SQLITE_OPE
1b6d0 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68  N_CREATE] and th
1b6e0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
1b6f0 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  not.**          
1b700 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74  previously exist
1b710 2c 20 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70  , then an attemp
1b720 74 20 69 73 20 6d 61 64 65 20 74 6f 20 63 72 65  t is made to cre
1b730 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ate and.**      
1b740 20 20 20 20 69 6e 69 74 69 61 6c 69 7a 65 20 74      initialize t
1b750 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a  he database..**.
1b760 2a 2a 20 7b 48 31 32 37 31 37 7d 20 49 66 20 74  ** {H12717} If t
1b770 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1b780 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
1b790 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1b7a0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
1b7b0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
1b7c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1b7d0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
1b7e0 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65 2c  then an private,
1b7f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68  .**          eph
1b800 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72  emeral, in-memor
1b810 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72  y database is cr
1b820 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
1b830 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20  nnection..**    
1b840 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53        <todo>Is S
1b850 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1b860 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  E|SQLITE_OPEN_RE
1b870 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64  ADWRITE required
1b880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
1b890 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1b8a0 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  )?</todo>.**.** 
1b8b0 7b 48 31 32 37 31 39 7d 20 49 66 20 74 68 65 20  {H12719} If the 
1b8c0 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c  filename is NULL
1b8d0 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72   or an empty str
1b8e0 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
1b8f0 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ate,.**         
1b900 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e 2d 64 69   ephemeral on-di
1b910 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
1b920 20 62 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20   be created..** 
1b930 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49           <todo>I
1b940 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  s SQLITE_OPEN_CR
1b950 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e  EATE|SQLITE_OPEN
1b960 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69  _READWRITE requi
1b970 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
1b980 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  in sqlite3_open_
1b990 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  v2()?</todo>.**.
1b9a0 2a 2a 20 7b 48 31 32 37 32 31 7d 20 54 68 65 20  ** {H12721} The 
1b9b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1b9c0 74 69 6f 6e 5d 20 63 72 65 61 74 65 64 20 62 79  tion] created by
1b9d0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1b9e0 32 28 46 2c 44 2c 47 2c 56 29 5d 0a 2a 2a 20 20  2(F,D,G,V)].**  
1b9f0 20 20 20 20 20 20 20 20 77 69 6c 6c 20 75 73 65          will use
1ba00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1ba10 73 5d 20 6f 62 6a 65 63 74 20 69 64 65 6e 74 69  s] object identi
1ba20 66 69 65 64 20 62 79 20 74 68 65 20 56 20 70 61  fied by the V pa
1ba30 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 20 20 20 20  rameter,.**     
1ba40 20 20 20 20 20 6f 72 20 74 68 65 20 64 65 66 61       or the defa
1ba50 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1ba60 5d 20 6f 62 6a 65 63 74 20 69 66 20 56 20 69 73  ] object if V is
1ba70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1ba80 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 33 7d 20  .**.** {H12723} 
1ba90 54 77 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f  Two [database co
1baa0 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20  nnections] will 
1bab0 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63  share a common c
1bac0 61 63 68 65 20 69 66 20 62 6f 74 68 20 77 65 72  ache if both wer
1bad0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70  e.**          op
1bae0 65 6e 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ened with the sa
1baf0 6d 65 20 56 46 53 20 77 68 69 6c 65 20 5b 73 68  me VFS while [sh
1bb00 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
1bb10 20 77 61 73 20 65 6e 61 62 6c 65 64 20 61 6e 64   was enabled and
1bb20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20  .**          if 
1bb30 62 6f 74 68 20 66 69 6c 65 6e 61 6d 65 73 20 63  both filenames c
1bb40 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 75 73 69  ompare equal usi
1bb50 6e 67 20 6d 65 6d 63 6d 70 28 29 20 61 66 74 65  ng memcmp() afte
1bb60 72 20 68 61 76 69 6e 67 20 62 65 65 6e 0a 2a 2a  r having been.**
1bb70 20 20 20 20 20 20 20 20 20 20 70 72 6f 63 65 73            proces
1bb80 73 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  sed by the [sqli
1bb90 74 65 33 5f 76 66 73 20 7c 20 78 46 75 6c 6c 50  te3_vfs | xFullP
1bba0 61 74 68 6e 61 6d 65 5d 20 6d 65 74 68 6f 64 20  athname] method 
1bbb0 6f 66 20 74 68 65 20 56 46 53 2e 0a 2a 2f 0a 69  of the VFS..*/.i
1bbc0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
1bbd0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
1bbe0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1bbf0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1bc00 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
1bc10 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
1bc20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1bc30 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1bc40 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1bc50 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
1bc60 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
1bc70 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1bc80 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
1bc90 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1bca0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
1bcb0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1bcc0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
1bcd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1bce0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
1bcf0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1bd00 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1bd10 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
1bd20 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
1bd30 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1bd40 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1bd50 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
1bd60 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
1bd70 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
1bd80 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
1bd90 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
1bda0 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
1bdb0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1bdc0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
1bdd0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 48   And Messages {H
1bde0 31 32 38 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a  12800} <S60200>.
1bdf0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1be00 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
1be10 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1be20 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
1be30 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
1be40 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1be50 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1be60 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
1be70 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
1be80 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
1be90 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
1bea0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
1beb0 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
1bec0 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
1bed0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1bee0 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
1bef0 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
1bf00 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
1bf10 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1bf20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
1bf30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1bf40 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
1bf50 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
1bf60 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
1bf70 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
1bf80 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
1bf90 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
1bfa0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
1bfb0 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
1bfc0 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68  ..** Memory to h
1bfd0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
1bfe0 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
1bff0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
1c000 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
1c010 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
1c020 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
1c030 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
1c040 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
1c050 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
1c060 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
1c070 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
1c080 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
1c090 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1c0a0 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
1c0b0 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
1c0c0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ons..**.** If an
1c0d0 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
1c0e0 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
1c0f0 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
1c100 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
1c110 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
1c120 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
1c130 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
1c140 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
1c150 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
1c160 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
1c170 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
1c180 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1c190 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 31  S:.**.** {H12801
1c1a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
1c1b0 72 72 63 6f 64 65 28 44 29 5d 20 69 6e 74 65 72  rrcode(D)] inter
1c1c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
1c1d0 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20   numeric.**     
1c1e0 20 20 20 20 20 5b 72 65 73 75 6c 74 20 63 6f 64       [result cod
1c1f0 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
1c200 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
1c210 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1c220 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ly.**          f
1c230 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20  ailed interface 
1c240 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20  call associated 
1c250 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
1c260 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1c270 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 33 7d  ..**.** {H12803}
1c280 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   The [sqlite3_er
1c290 72 6d 73 67 28 44 29 5d 20 61 6e 64 20 5b 73 71  rmsg(D)] and [sq
1c2a0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44  lite3_errmsg16(D
1c2b0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
1c2c0 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e  nterfaces return
1c2d0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
1c2e0 65 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  e text that desc
1c2f0 72 69 62 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  ribes.**        
1c300 20 20 74 68 65 20 65 72 72 6f 72 20 69 6e 20 74    the error in t
1c310 68 65 20 6d 6f 73 74 6c 79 20 72 65 63 65 6e 74  he mostly recent
1c320 6c 79 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66  ly failed interf
1c330 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20  ace call,.**    
1c340 20 20 20 20 20 20 65 6e 63 6f 64 65 64 20 61 73        encoded as
1c350 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1c360 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
1c370 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  vely..**.** {H12
1c380 38 30 37 7d 20 54 68 65 20 73 74 72 69 6e 67 73  807} The strings
1c390 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1c3a0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
1c3b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
1c3c0 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  msg16()].**     
1c3d0 20 20 20 20 20 61 72 65 20 76 61 6c 69 64 20 75       are valid u
1c3e0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 53 51  ntil the next SQ
1c3f0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 63  Lite interface c
1c400 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38  all..**.** {H128
1c410 30 38 7d 20 43 61 6c 6c 73 20 74 6f 20 41 50 49  08} Calls to API
1c420 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 64   routines that d
1c430 6f 20 6e 6f 74 20 72 65 74 75 72 6e 20 61 6e 20  o not return an 
1c440 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
1c450 20 20 20 20 20 20 20 28 65 78 61 6d 70 6c 65 3a         (example:
1c460 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
1c470 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a  ount()]) do not.
1c480 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68 61 6e  **          chan
1c490 67 65 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ge the error cod
1c4a0 65 20 6f 72 20 6d 65 73 73 61 67 65 20 72 65 74  e or message ret
1c4b0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
1c4c0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72       [sqlite3_er
1c4d0 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74  rcode()], [sqlit
1c4e0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72  e3_errmsg()], or
1c4f0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1c500 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  16()]..**.** {H1
1c510 32 38 30 39 7d 20 49 6e 74 65 72 66 61 63 65 73  2809} Interfaces
1c520 20 74 68 61 74 20 61 72 65 20 6e 6f 74 20 61 73   that are not as
1c530 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
1c540 73 70 65 63 69 66 69 63 0a 2a 2a 20 20 20 20 20  specific.**     
1c550 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
1c560 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 65 78 61 6d  onnection] (exam
1c570 70 6c 65 73 3a 0a 2a 2a 20 20 20 20 20 20 20 20  ples:.**        
1c580 20 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e    [sqlite3_mprin
1c590 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  tf()] or [sqlite
1c5a0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
1c5b0 63 61 63 68 65 28 29 5d 0a 2a 2a 20 20 20 20 20  cache()].**     
1c5c0 20 20 20 20 20 64 6f 20 6e 6f 74 20 63 68 61 6e       do not chan
1c5d0 67 65 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  ge the values re
1c5e0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20  turned by.**    
1c5f0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
1c600 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69  rrcode()], [sqli
1c610 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f  te3_errmsg()], o
1c620 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
1c630 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  g16()]..*/.int s
1c640 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
1c650 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
1c660 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1c670 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
1c680 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
1c690 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1c6a0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1c6b0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
1c6c0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
1c6d0 20 7b 48 31 33 30 30 30 7d 20 3c 48 31 33 30 31   {H13000} <H1301
1c6e0 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
1c6f0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
1c700 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
1c710 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
1c720 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
1c730 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
1c740 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
1c750 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1c760 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
1c770 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
1c780 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
1c790 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
1c7a0 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
1c7b0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
1c7c0 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
1c7d0 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
1c7e0 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
1c7f0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
1c800 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
1c810 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
1c820 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
1c830 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
1c840 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1c850 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
1c860 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
1c870 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
1c880 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
1c890 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
1c8a0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
1c8b0 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
1c8c0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
1c8d0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
1c8e0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
1c8f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1c900 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
1c910 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
1c920 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
1c930 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
1c940 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
1c950 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
1c960 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
1c970 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
1c980 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
1c990 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
1c9a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
1c9b0 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
1c9c0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
1c9d0 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
1c9e0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
1c9f0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
1ca00 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1ca10 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
1ca20 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
1ca30 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
1ca40 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
1ca50 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
1ca60 6d 65 20 4c 69 6d 69 74 73 20 7b 48 31 32 37 36  me Limits {H1276
1ca70 30 7d 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a  0} <S20600>.**.*
1ca80 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
1ca90 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
1caa0 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
1cab0 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
1cac0 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
1cad0 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
1cae0 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
1caf0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1cb00 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
1cb10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cb20 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
1cb30 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
1cb40 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
1cb50 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1cb60 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
1cb70 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
1cb80 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
1cb90 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
1cba0 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
1cbb0 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
1cbc0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
1cbd0 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
1cbe0 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
1cbf0 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63  truct.  The func
1cc00 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1cc10 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a   old limit..**.*
1cc20 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d  * If the new lim
1cc30 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
1cc40 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
1cc50 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
1cc60 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d 69  .** For the limi
1cc70 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51  t category of SQ
1cc80 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74  LITE_LIMIT_XYZ t
1cc90 68 65 72 65 20 69 73 20 61 20 68 61 72 64 20 75  here is a hard u
1cca0 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64 20 73 65  pper.** bound se
1ccb0 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74  t by a compile-t
1ccc0 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73 73  ime C preprocess
1ccd0 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 53  or macro named S
1cce0 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a  QLITE_MAX_XYZ..*
1ccf0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
1cd00 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
1cd10 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
1cd20 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73  _".).** Attempts
1cd30 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
1cd40 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
1cd50 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
1cd60 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
1cd70 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
1cd80 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69   hard upper limi
1cd90 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d  t..**.** Run tim
1cda0 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
1cdb0 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
1cdc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
1cdd0 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
1cde0 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
1cdf0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
1ce00 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
1ce10 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
1ce20 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
1ce30 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
1ce40 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
1ce50 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
1ce60 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
1ce70 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
1ce80 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
1ce90 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
1cea0 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
1ceb0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
1cec0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
1ced0 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
1cee0 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
1cef0 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
1cf00 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
1cf10 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
1cf20 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
1cf30 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
1cf40 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
1cf50 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
1cf60 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
1cf70 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
1cf80 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
1cf90 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
1cfa0 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
1cfb0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
1cfc0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
1cfd0 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
1cfe0 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
1cff0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1d000 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
1d010 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
1d020 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
1d030 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
1d040 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
1d050 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
1d060 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
1d070 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
1d080 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
1d090 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
1d0a0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
1d0b0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
1d0c0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
1d0d0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
1d0e0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
1d0f0 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
1d100 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  NTS:.**.** {H127
1d110 36 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  62} A successful
1d120 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1d130 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20  3_limit(D,C,V)] 
1d140 77 68 65 72 65 20 56 20 69 73 0a 2a 2a 20 20 20  where V is.**   
1d150 20 20 20 20 20 20 20 70 6f 73 69 74 69 76 65 20         positive 
1d160 63 68 61 6e 67 65 73 20 74 68 65 20 6c 69 6d 69  changes the limi
1d170 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  t on the size of
1d180 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20   construct C in 
1d190 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1d1a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1d1b0 74 69 6f 6e 5d 20 44 20 74 6f 20 74 68 65 20 6c  tion] D to the l
1d1c0 65 73 73 65 72 20 6f 66 20 56 20 61 6e 64 20 74  esser of V and t
1d1d0 68 65 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a  he hard upper.**
1d1e0 20 20 20 20 20 20 20 20 20 20 62 6f 75 6e 64 20            bound 
1d1f0 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 43  on the size of C
1d200 20 74 68 61 74 20 69 73 20 73 65 74 20 61 74 20   that is set at 
1d210 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a  compile-time..**
1d220 0a 2a 2a 20 7b 48 31 32 37 36 36 7d 20 41 20 73  .** {H12766} A s
1d230 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1d240 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  o [sqlite3_limit
1d250 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56  (D,C,V)] where V
1d260 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
1d270 20 20 20 20 20 20 20 20 20 6c 65 61 76 65 73 20           leaves 
1d280 74 68 65 20 73 74 61 74 65 20 6f 66 20 74 68 65  the state of the
1d290 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1d2a0 63 74 69 6f 6e 5d 20 44 20 75 6e 63 68 61 6e 67  ction] D unchang
1d2b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36  ed..**.** {H1276
1d2c0 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  9} A successful 
1d2d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1d2e0 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 72  _limit(D,C,V)] r
1d2f0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
1d300 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
1d310 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65  the limit on the
1d320 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75   size of constru
1d330 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ct C in the.**  
1d340 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
1d350 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1d360 61 73 20 69 74 20 77 61 73 20 70 72 69 6f 72 20  as it was prior 
1d370 74 6f 20 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a  to the call..*/.
1d380 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
1d390 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
1d3a0 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
1d3b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d3c0 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
1d3d0 20 43 61 74 65 67 6f 72 69 65 73 20 7b 48 31 32   Categories {H12
1d3e0 37 39 30 7d 20 3c 48 31 32 37 36 30 3e 0a 2a 2a  790} <H12760>.**
1d3f0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
1d400 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d  t category} {lim
1d410 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
1d420 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
1d430 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
1d440 6f 75 73 20 61 73 70 65 63 74 73 20 6f 66 20 61  ous aspects of a
1d450 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1d460 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 63  ction].** that c
1d470 61 6e 20 62 65 20 6c 69 6d 69 74 65 64 20 69 6e  an be limited in
1d480 20 73 69 7a 65 20 62 79 20 63 61 6c 6c 73 20 74   size by calls t
1d490 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  o [sqlite3_limit
1d4a0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e  ()]..** The mean
1d4b0 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
1d4c0 6f 75 73 20 6c 69 6d 69 74 73 20 61 72 65 20 61  ous limits are a
1d4d0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1d4e0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
1d4f0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
1d500 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1d510 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
1d520 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
1d530 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
1d540 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  .<dd>.**.** <dt>
1d550 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1d560 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1d570 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1d580 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
1d590 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
1d5a0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1d5b0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
1d5c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1d5d0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1d5e0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
1d5f0 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
1d600 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
1d610 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45  lt set of a SELE
1d620 43 54 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  CT or the maximu
1d630 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1d640 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
1d650 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
1d660 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
1d670 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a   clause.</dd>.**
1d680 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1d690 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
1d6a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1d6b0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
1d6c0 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
1d6d0 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
1d6e0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
1d6f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
1d700 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
1d710 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1d720 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1d730 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
1d740 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
1d750 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ement.</dd>.**.*
1d760 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1d770 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
1d780 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1d790 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
1d7a0 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
1d7b0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
1d7c0 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
1d7d0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
1d7e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  QL statement.</d
1d7f0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1d800 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
1d810 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
1d820 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1d830 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
1d840 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
1d850 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1d860 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
1d870 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
1d880 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1d890 75 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68 65  umber of attache
1d8a0 64 20 64 61 74 61 62 61 73 65 73 2e 3c 2f 64 64  d databases.</dd
1d8b0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1d8c0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
1d8d0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
1d8e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1d8f0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
1d900 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
1d910 65 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b 45 20  ent to the LIKE 
1d920 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72 61  or.** GLOB opera
1d930 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tors.</dd>.**.**
1d940 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1d950 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1d960 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
1d970 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1d980 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e   of variables in
1d990 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1d9a0 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65  t that can.** be
1d9b0 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20   bound.</dd>.** 
1d9c0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
1d9d0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
1d9e0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
1d9f0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
1da00 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
1da10 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
1da20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
1da30 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1da40 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
1da50 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
1da60 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1da70 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
1da80 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
1da90 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1daa0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1dab0 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
1dac0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1dad0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
1dae0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
1daf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1db00 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
1db10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
1db20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1db30 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
1db40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
1db50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1db60 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
1db70 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
1db80 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
1db90 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1dba0 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
1dbb0 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   9../*.** CAPI3R
1dbc0 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
1dbd0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b   SQL Statement {
1dbe0 48 31 33 30 31 30 7d 20 3c 53 31 30 30 30 30 3e  H13010} <S10000>
1dbf0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
1dc00 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
1dc10 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
1dc20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
1dc30 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
1dc40 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
1dc50 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
1dc60 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
1dc70 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
1dc80 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
1dc90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1dca0 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
1dcb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1dcc0 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
1dcd0 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 63 61 6c  m a.** prior cal
1dce0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
1dcf0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1dd00 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 20 5b 73  open_v2()] or [s
1dd10 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1dd20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
1dd30 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
1dd40 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
1dd50 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
1dd60 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
1dd70 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
1dd80 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
1dd90 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1dda0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
1ddb0 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
1ddc0 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
1ddd0 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
1dde0 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
1ddf0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1de00 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
1de10 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  TF-16..**.** If 
1de20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
1de30 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  nt is less than 
1de40 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
1de50 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
1de60 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
1de70 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20 6e  terminator. If n
1de80 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
1de90 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
1dea0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
1deb0 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
1dec0 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
1ded0 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20    When nByte is 
1dee0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
1def0 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
1df00 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
1df10 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
1df20 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
1df30 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
1df40 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
1df50 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
1df60 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
1df70 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
1df80 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
1df90 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
1dfa0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
1dfb0 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
1dfc0 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
1dfd0 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
1dfe0 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
1dff0 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
1e000 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
1e010 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
1e020 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
1e030 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
1e040 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
1e050 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
1e060 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a  inator bytes..**
1e070 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  .** *pzTail is m
1e080 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
1e090 74 68 65 20 66 69 72 73 74 20 62 79 74 65 20 70  the first byte p
1e0a0 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
1e0b0 68 65 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c 20  he.** first SQL 
1e0c0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
1e0d0 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
1e0e0 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 20  es only compile 
1e0f0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 73 74 61  the first.** sta
1e100 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
1e110 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
1e120 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77  ft pointing to w
1e130 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75  hat remains.** u
1e140 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
1e150 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74   *ppStmt is left
1e160 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
1e170 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
1e180 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1e190 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
1e1a0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
1e1b0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 49 66  te3_step()].  If
1e1c0 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
1e1d0 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
1e1e0 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
1e1f0 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78  If the input tex
1e200 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  t contains no SQ
1e210 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
1e220 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73  is an empty.** s
1e230 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
1e240 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
1e250 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
1e260 0a 2a 2a 20 7b 41 31 33 30 31 38 7d 20 54 68 65  .** {A13018} The
1e270 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
1e280 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
1e290 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
1e2a0 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
1e2b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
1e2c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
1e2d0 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
1e2e0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1e2f0 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20  th it..**.** On 
1e300 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45  success, [SQLITE
1e310 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
1e320 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  , otherwise an [
1e330 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
1e340 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
1e350 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
1e360 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
1e370 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1e380 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
1e390 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
1e3a0 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
1e3b0 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
1e3c0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
1e3d0 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
1e3e0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
1e3f0 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
1e400 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
1e410 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e  scouraged..** In
1e420 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
1e430 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
1e440 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
1e450 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
1e460 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
1e470 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
1e480 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
1e490 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
1e4a0 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
1e4b0 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
1e4c0 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
1e4d0 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
1e4e0 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20  e a differently 
1e4f0 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a  in two ways:.**.
1e500 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
1e510 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
1e520 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
1e530 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
1e540 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
1e550 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
1e560 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
1e570 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
1e580 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
1e590 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
1e5a0 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
1e5b0 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
1e5c0 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
1e5d0 20 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 68   If the schema h
1e5e0 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a  as changed in.**
1e5f0 20 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65   a way that make
1e600 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1e610 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c  no longer valid,
1e620 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1e630 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20  ] will still.** 
1e640 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53  return [SQLITE_S
1e650 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c  CHEMA].  But unl
1e660 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ike the legacy b
1e670 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45  ehavior, [SQLITE
1e680 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e  _SCHEMA] is.** n
1e690 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72  ow a fatal error
1e6a0 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  .  Calling [sqli
1e6b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1e6c0 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74  ] again will not
1e6d0 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72   make the.** err
1e6e0 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74  or go away.  Not
1e6f0 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f  e: use [sqlite3_
1e700 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e  errmsg()] to fin
1e710 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66  d the text.** of
1e720 20 74 68 65 20 70 61 72 73 69 6e 67 20 65 72 72   the parsing err
1e730 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 20  or that results 
1e740 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43  in an [SQLITE_SC
1e750 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a  HEMA] return..**
1e760 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
1e770 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72  >.** When an err
1e780 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
1e790 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
1e7a0 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
1e7b0 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
1e7c0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
1e7d0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
1e7e0 63 6f 64 65 73 5d 2e 20 20 54 68 65 20 6c 65 67  codes].  The leg
1e7f0 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
1e800 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
1e810 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
1e820 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
1e830 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
1e840 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
1e850 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c  .** and you woul
1e860 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
1e870 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
1e880 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1e890 5d 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  ] in order.** to
1e8a0 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
1e8b0 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
1e8c0 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
1e8d0 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
1e8e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
1e8f0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
1e900 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
1e910 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
1e920 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
1e930 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
1e940 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1e950 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 31 7d 20  .**.** {H13011} 
1e960 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  The [sqlite3_pre
1e970 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  pare(db,zSql,...
1e980 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
1e990 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
1e9a0 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e  are_v2(db,zSql,.
1e9b0 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  ..)] interfaces 
1e9c0 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
1e9d0 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69            text i
1e9e0 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72  n their zSql par
1e9f0 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 38 2e  ameter as UTF-8.
1ea00 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 32 7d 20  .**.** {H13012} 
1ea10 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  The [sqlite3_pre
1ea20 70 61 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e  pare16(db,zSql,.
1ea30 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ..)] and.**     
1ea40 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
1ea50 65 70 61 72 65 31 36 5f 76 32 28 64 62 2c 7a 53  epare16_v2(db,zS
1ea60 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ql,...)] interfa
1ea70 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68  ces interpret th
1ea80 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65  e.**          te
1ea90 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c  xt in their zSql
1eaa0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54   parameter as UT
1eab0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1eac0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
1ead0 2a 0a 2a 2a 20 7b 48 31 33 30 31 33 7d 20 49 66  *.** {H13013} If
1eae0 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
1eaf0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
1eb00 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
1eb10 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a  ql,nByte,...)].*
1eb20 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 69  *          and i
1eb30 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 6c  ts variants is l
1eb40 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
1eb50 68 65 20 53 51 4c 20 74 65 78 74 20 69 73 0a 2a  he SQL text is.*
1eb60 2a 20 20 20 20 20 20 20 20 20 20 72 65 61 64 20  *          read 
1eb70 66 72 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65 61  from zSql is rea
1eb80 64 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  d up to the firs
1eb90 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
1eba0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 34  r..**.** {H13014
1ebb0 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61  } If the nByte a
1ebc0 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
1ebd0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
1ebe0 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e  b,zSql,nByte,...
1ebf0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1ec00 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  nd its variants 
1ec10 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
1ec20 20 74 68 65 6e 20 61 74 20 6d 6f 73 74 20 6e 42   then at most nB
1ec30 79 74 65 73 20 62 79 74 65 73 20 6f 66 0a 2a 2a  ytes bytes of.**
1ec40 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 74 65            SQL te
1ec50 78 74 20 69 73 20 72 65 61 64 20 66 72 6f 6d 20  xt is read from 
1ec60 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  zSql..**.** {H13
1ec70 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33  015} In [sqlite3
1ec80 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
1ec90 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d  Sql,N,P,pzTail)]
1eca0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
1ecb0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66  s.**          if
1ecc0 20 74 68 65 20 7a 53 71 6c 20 69 6e 70 75 74 20   the zSql input 
1ecd0 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6d 6f  text contains mo
1ece0 72 65 20 74 68 61 6e 20 6f 6e 65 20 53 51 4c 20  re than one SQL 
1ecf0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20  statement.**    
1ed00 20 20 20 20 20 20 61 6e 64 20 70 7a 54 61 69 6c        and pzTail
1ed10 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
1ed20 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
1ed30 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
1ed40 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  he.**          f
1ed50 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74  irst byte past t
1ed60 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
1ed70 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
1ed80 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20  t in zSql..**   
1ed90 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68 61         <todo>Wha
1eda0 74 20 64 6f 65 73 20 2a 70 7a 54 61 69 6c 20 70  t does *pzTail p
1edb0 6f 69 6e 74 20 74 6f 20 69 66 20 74 68 65 72 65  oint to if there
1edc0 20 69 73 20 6f 6e 65 20 73 74 61 74 65 6d 65 6e   is one statemen
1edd0 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  t?</todo>.**.** 
1ede0 7b 48 31 33 30 31 36 7d 20 41 20 73 75 63 63 65  {H13016} A succe
1edf0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
1ee00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1ee10 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74  2(db,zSql,N,ppSt
1ee20 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  mt,...)].**     
1ee30 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f 66 20 69       or one of i
1ee40 74 73 20 76 61 72 69 61 6e 74 73 20 77 72 69 74  ts variants writ
1ee50 65 73 20 69 6e 74 6f 20 2a 70 70 53 74 6d 74 20  es into *ppStmt 
1ee60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
1ee70 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ew.**          [
1ee80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ee90 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  nt] or a pointer
1eea0 20 74 6f 20 4e 55 4c 4c 20 69 66 20 7a 53 71 6c   to NULL if zSql
1eeb0 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20   contains.**    
1eec0 20 20 20 20 20 20 6e 6f 74 68 69 6e 67 20 6f 74        nothing ot
1eed0 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70  her than whitesp
1eee0 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e  ace or comments.
1eef0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 39 7d 20  .**.** {H13019} 
1ef00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  The [sqlite3_pre
1ef10 70 61 72 65 5f 76 32 28 29 5d 20 69 6e 74 65 72  pare_v2()] inter
1ef20 66 61 63 65 20 61 6e 64 20 69 74 73 20 76 61 72  face and its var
1ef30 69 61 6e 74 73 20 72 65 74 75 72 6e 0a 2a 2a 20  iants return.** 
1ef40 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
1ef50 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70 70 72 6f  _OK] or an appro
1ef60 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
1ef70 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c 75 72 65  de] upon failure
1ef80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 32 31 7d  ..**.** {H13021}
1ef90 20 42 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   Before [sqlite3
1efa0 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c  _prepare(db,zSql
1efb0 2c 6e 42 79 74 65 2c 70 70 53 74 6d 74 2c 70 7a  ,nByte,ppStmt,pz
1efc0 54 61 69 6c 29 5d 20 6f 72 20 69 74 73 0a 2a 2a  Tail)] or its.**
1efd0 20 20 20 20 20 20 20 20 20 20 76 61 72 69 61 6e            varian
1efe0 74 73 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  ts returns an er
1eff0 72 6f 72 20 28 61 6e 79 20 76 61 6c 75 65 20 6f  ror (any value o
1f000 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1f010 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20 20 20 20 20  E_OK]),.**      
1f020 20 20 20 20 74 68 65 79 20 66 69 72 73 74 20 73      they first s
1f030 65 74 20 2a 70 70 53 74 6d 74 20 74 6f 20 4e 55  et *ppStmt to NU
1f040 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
1f050 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
1f060 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1f070 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1f080 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1f090 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1f0a0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1f0b0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
1f0c0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1f0d0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1f0e0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1f0f0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1f100 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1f110 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1f120 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1f130 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1f140 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
1f150 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1f160 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1f170 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1f180 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1f190 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f1a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1f1b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1f1c0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1f1d0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1f1e0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1f1f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1f200 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1f210 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1f220 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1f230 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1f240 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1f250 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1f260 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1f270 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1f280 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1f290 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1f2a0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1f2b0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1f2c0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1f2d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1f2e0 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
1f2f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1f300 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1f310 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1f320 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
1f330 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1f340 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
1f350 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1f360 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1f370 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1f380 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1f390 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1f3a0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1f3b0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1f3c0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1f3d0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
1f3e0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1f3f0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1f400 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1f410 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1f420 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
1f430 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1f440 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1f450 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1f460 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
1f470 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1f480 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1f490 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
1f4a0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1f4b0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1f4c0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1f4d0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1f4e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1f4f0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1f500 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1f510 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1f520 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
1f530 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1f540 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1f550 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
1f560 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 3a 20 52  /*.** CAPIREF: R
1f570 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
1f580 65 6e 74 20 53 51 4c 20 7b 48 31 33 31 30 30 7d  ent SQL {H13100}
1f590 20 3c 48 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H13000>.**.** 
1f5a0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1f5b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
1f5c0 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
1f5d0 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
1f5e0 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
1f5f0 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
1f600 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f610 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
1f620 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
1f630 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
1f640 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
1f650 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
1f660 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f670 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  6_v2()]..**.** I
1f680 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1f690 20 7b 48 31 33 31 30 31 7d 20 49 66 20 74 68 65   {H13101} If the
1f6a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f6b0 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20  ment] passed as 
1f6c0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
1f6d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1f6e0 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20  ite3_sql()] was 
1f6f0 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
1f700 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
1f710 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a  repare_v2()] or.
1f720 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1f730 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1f740 32 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69  2()], then [sqli
1f750 74 65 33 5f 73 71 6c 28 29 5d 20 72 65 74 75 72  te3_sql()] retur
1f760 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ns.**          a
1f770 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
1f780 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1f790 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
1f7a0 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1f7b0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  g.**          of
1f7c0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 53 51   the original SQ
1f7d0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  L statement..**.
1f7e0 2a 2a 20 7b 48 31 33 31 30 32 7d 20 49 66 20 74  ** {H13102} If t
1f7f0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
1f800 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61  tement] passed a
1f810 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
1f820 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
1f830 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61  qlite3_sql()] wa
1f840 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  s compiled using
1f850 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
1f860 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a  _prepare()] or.*
1f870 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1f880 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1f890 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  , then [sqlite3_
1f8a0 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 20 61  sql()] returns a
1f8b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1f8c0 2a 0a 2a 2a 20 7b 48 31 33 31 30 33 7d 20 54 68  *.** {H13103} Th
1f8d0 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  e string returne
1f8e0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 71  d by [sqlite3_sq
1f8f0 6c 28 53 29 5d 20 69 73 20 76 61 6c 69 64 20 75  l(S)] is valid u
1f900 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20 20 20 20  ntil the.**     
1f910 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
1f920 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 64  tatement] S is d
1f930 65 6c 65 74 65 64 20 75 73 69 6e 67 20 5b 73 71  eleted using [sq
1f940 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
1f950 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
1f960 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
1f970 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
1f980 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
1f990 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
1f9a0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
1f9b0 6a 65 63 74 20 7b 48 31 35 30 30 30 7d 20 3c 53  ject {H15000} <S
1f9c0 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  20200>.** KEYWOR
1f9d0 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
1f9e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
1f9f0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1fa00 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
1fa10 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
1fa20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1fa30 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
1fa40 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
1fa50 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
1fa60 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
1fa70 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
1fa80 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
1fa90 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
1faa0 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
1fab0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
1fac0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1fad0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
1fae0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
1faf0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
1fb00 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
1fb10 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
1fb20 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
1fb30 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
1fb40 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
1fb50 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
1fb60 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
1fb70 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
1fb80 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
1fb90 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
1fba0 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
1fbb0 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
1fbc0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
1fbd0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
1fbe0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
1fbf0 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
1fc00 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
1fc10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
1fc20 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
1fc30 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
1fc40 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
1fc50 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
1fc60 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
1fc70 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
1fc80 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
1fc90 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
1fca0 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
1fcb0 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
1fcc0 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c  eld.  A internal
1fcd0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
1fce0 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
1fcf0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1fd00 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
1fd10 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
1fd20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
1fd30 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1fd40 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
1fd50 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
1fd60 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
1fd70 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
1fd80 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1fd90 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
1fda0 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
1fdb0 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
1fdc0 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
1fdd0 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
1fde0 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
1fdf0 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
1fe00 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
1fe10 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
1fe20 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
1fe30 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
1fe40 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
1fe50 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
1fe60 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1fe70 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1fe80 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1fe90 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
1fea0 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
1feb0 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
1fec0 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
1fed0 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
1fee0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
1fef0 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
1ff00 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
1ff10 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
1ff20 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65  on between betwe
1ff30 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
1ff40 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1ff50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1ff60 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
1ff70 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
1ff80 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
1ff90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1ffa0 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
1ffb0 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
1ffc0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
1ffd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1ffe0 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
1fff0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
20000 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
20010 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cted..** The sql
20020 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
20030 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
20040 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
20050 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
20060 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
20070 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
20080 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
20090 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
200a0 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
200b0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
200c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
200d0 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
200e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
200f0 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
20100 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
20110 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
20120 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
20130 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
20140 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
20150 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
20160 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
20170 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
20180 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
20190 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
201a0 63 74 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 30  ct {H16001} <S20
201b0 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  200>.**.** The c
201c0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
201d0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
201e0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
201f0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
20200 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
20210 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74  ct.  A pointer t
20220 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
20230 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
20240 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
20250 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
20260 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
20270 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
20280 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
20290 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
202a0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
202b0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
202c0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
202d0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
202e0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
202f0 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
20300 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
20310 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
20320 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
20330 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
20340 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
20350 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
20360 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
20370 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
20380 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
20390 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
203a0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
203b0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
203c0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
203d0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
203e0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
203f0 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
20400 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
20410 73 20 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 33  s {H13500} <S703
20420 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
20430 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
20440 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
20450 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
20460 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
20470 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
20480 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
20490 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
204a0 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a  er binding}.**.*
204b0 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72  * In the SQL str
204c0 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73  ings input to [s
204d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
204e0 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
204f0 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
20500 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
20510 65 64 20 62 79 20 61 20 70 61 72 61 6d 65 74 65  ed by a paramete
20520 72 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73  r in one of thes
20530 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c  e forms:.**.** <
20540 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
20550 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
20560 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
20570 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
20580 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
20590 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72  **.** In the par
205a0 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f  ameter forms sho
205b0 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20  wn above NNN is 
205c0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
205d0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69  al,.** and VVV i
205e0 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72  s an alpha-numer
205f0 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  ic parameter nam
20600 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66  e. The values of
20610 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
20620 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
20630 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
20640 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
20650 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
20660 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
20670 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
20680 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
20690 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
206a0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
206b0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
206c0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
206d0 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
206e0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
206f0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
20700 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
20710 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
20720 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20730 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
20740 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nts..**.** The s
20750 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
20760 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
20770 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
20780 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54   to be set..** T
20790 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
207a0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
207b0 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68   index of 1.  Wh
207c0 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
207d0 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
207e0 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
207f0 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
20800 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
20810 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
20820 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
20830 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
20840 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
20850 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
20860 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
20870 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
20880 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
20890 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
208a0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
208b0 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54  I if desired.  T
208c0 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
208d0 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
208e0 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
208f0 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e  f NNN..** The NN
20900 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
20910 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
20920 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
20930 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
20940 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
20950 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
20960 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
20970 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  999)..**.** The 
20980 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
20990 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
209a0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
209b0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  eter..**.** In t
209c0 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
209d0 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
209e0 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
209f0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
20a00 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
20a10 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
20a20 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
20a30 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
20a40 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
20a50 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
20a60 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
20a70 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
20a80 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ters..** If the 
20a90 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
20aa0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
20ab0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
20ac0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
20ad0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
20ae0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
20af0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
20b00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
20b10 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
20b20 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
20b30 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
20b40 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
20b50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
20b60 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
20b70 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
20b80 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
20b90 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
20ba0 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
20bb0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
20bc0 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72   If the fifth ar
20bd0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
20be0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
20bf0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
20c00 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
20c10 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
20c20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
20c30 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
20c40 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
20c50 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
20c60 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74  e freed..** If t
20c70 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
20c80 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
20c90 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
20ca0 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
20cb0 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
20cc0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
20cd0 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
20ce0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
20cf0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
20d00 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
20d10 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  turns..**.** The
20d20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
20d30 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
20d40 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
20d50 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
20d60 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
20d70 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f   zeroes.  A zero
20d80 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
20d90 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
20da0 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
20db0 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
20dc0 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
20dd0 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
20de0 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
20df0 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
20e00 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
20e10 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
20e20 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
20e30 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
20e40 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
20e50 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
20e60 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
20e70 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
20e80 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65  s..** A negative
20e90 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
20ea0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
20eb0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
20ec0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   BLOB..**.** The
20ed0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
20ee0 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  ) routines must 
20ef0 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a  be called after.
20f00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
20f10 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69  are_v2()] (and i
20f20 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20  ts variants) or 
20f30 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
20f40 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20  ] and.** before 
20f50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20f60 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72  ..** Bindings ar
20f70 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
20f80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
20f90 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
20fa0 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  ** Unbound param
20fb0 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
20fc0 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
20fd0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
20fe0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
20ff0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
21000 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f  s or an error co
21010 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e  de if.** anythin
21020 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b  g goes wrong.  [
21030 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
21040 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
21050 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
21060 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
21070 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f  nge.  [SQLITE_NO
21080 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
21090 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
210a0 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  ls..** [SQLITE_M
210b0 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20  ISUSE] might be 
210c0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73  returned if thes
210d0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
210e0 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69  alled on a.** vi
210f0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68  rtual machine th
21100 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20  at is the wrong 
21110 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68  state or which h
21120 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  as already been 
21130 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65  finalized..** De
21140 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73  tection of misus
21150 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e  e is unreliable.
21160 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73    Applications s
21170 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64  hould not depend
21180 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49  .** on SQLITE_MI
21190 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53  SUSE returns.  S
211a0 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20  QLITE_MISUSE is 
211b0 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69  intended to indi
211c0 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69  cate a.** a logi
211d0 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61  c error in the a
211e0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74  pplication.  Fut
211f0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
21200 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
21210 70 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 61  panic rather tha
21220 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  n return SQLITE_
21230 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65  MISUSE..**.** Se
21240 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
21250 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21260 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
21270 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21280 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
21290 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
212a0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
212b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
212c0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
212d0 35 30 36 7d 20 54 68 65 20 5b 53 51 4c 20 73 74  506} The [SQL st
212e0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
212f0 5d 20 72 65 63 6f 67 6e 69 7a 65 73 20 74 6f 6b  ] recognizes tok
21300 65 6e 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 73  ens of the forms
21310 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 22 3f 22  .**          "?"
21320 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22  , "?NNN", "$VVV"
21330 2c 20 22 3a 56 56 56 22 2c 20 61 6e 64 20 22 40  , ":VVV", and "@
21340 56 56 56 22 20 61 73 20 53 51 4c 20 70 61 72 61  VVV" as SQL para
21350 6d 65 74 65 72 73 2c 0a 2a 2a 20 20 20 20 20 20  meters,.**      
21360 20 20 20 20 77 68 65 72 65 20 4e 4e 4e 20 69 73      where NNN is
21370 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66   any sequence of
21380 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 64 69 67   one or more dig
21390 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
213a0 61 6e 64 20 77 68 65 72 65 20 56 56 56 20 69 73  and where VVV is
213b0 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66   any sequence of
213c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 61 6c 70   one or more alp
213d0 68 61 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20  hanumeric.**    
213e0 20 20 20 20 20 20 63 68 61 72 61 63 74 65 72 73        characters
213f0 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61   or "::" optiona
21400 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  lly followed by 
21410 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  a string contain
21420 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
21430 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f  no spaces and co
21440 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 70  ntained within p
21450 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a  arentheses..**.*
21460 2a 20 7b 48 31 33 35 30 39 7d 20 54 68 65 20 69  * {H13509} The i
21470 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f 66 20  nitial value of 
21480 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
21490 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
214a0 7b 48 31 33 35 31 32 7d 20 54 68 65 20 69 6e 64  {H13512} The ind
214b0 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c  ex of an "?" SQL
214c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
214d0 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
214e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61  e.**          la
214f0 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 53  rgest index of S
21500 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
21510 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31 20 69  the left, or 1 i
21520 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
21530 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c 65 66  e "?" is the lef
21540 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
21550 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ter..**.** {H135
21560 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  15} The index of
21570 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70   an "?NNN" SQL p
21580 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
21590 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a  integer NNN..**.
215a0 2a 2a 20 7b 48 31 33 35 31 38 7d 20 54 68 65 20  ** {H13518} The 
215b0 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a 56 56  index of an ":VV
215c0 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72 20 22  V", "$VVV", or "
215d0 40 56 56 56 22 20 53 51 4c 20 70 61 72 61 6d 65  @VVV" SQL parame
215e0 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ter is.**       
215f0 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 74     the same as t
21600 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65 66 74  he index of left
21610 6d 6f 73 74 20 6f 63 63 75 72 72 65 6e 63 65 73  most occurrences
21620 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
21630 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
21640 65 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20  er, or one more 
21650 74 68 61 6e 20 74 68 65 20 6c 61 72 67 65 73 74  than the largest
21660 20 69 6e 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a   index over all.
21670 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61  **          para
21680 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 6c 65  meters to the le
21690 66 74 20 69 66 20 74 68 69 73 20 69 73 20 74 68  ft if this is th
216a0 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
216b0 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ce.**          o
216c0 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
216d0 2c 20 6f 72 20 31 20 69 66 20 74 68 69 73 20 69  , or 1 if this i
216e0 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 70  s the leftmost p
216f0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
21700 7b 48 31 33 35 32 31 7d 20 54 68 65 20 5b 53 51  {H13521} The [SQ
21710 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
21720 69 6c 65 72 5d 20 66 61 69 6c 73 20 77 69 74 68  iler] fails with
21730 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47   an [SQLITE_RANG
21740 45 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  E].**          e
21750 72 72 6f 72 20 69 66 20 74 68 65 20 69 6e 64 65  rror if the inde
21760 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
21770 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
21780 61 6e 20 31 0a 2a 2a 20 20 20 20 20 20 20 20 20  an 1.**         
21790 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
217a0 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
217b0 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52  e SQLITE_MAX_VAR
217c0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 0a 2a 2a 20  IABLE_NUMBER.** 
217d0 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
217e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32  er..**.** {H1352
217f0 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  4} Calls to [sql
21800 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
21810 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c   sqlite3_bind(S,
21820 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  N,V,...)].**    
21830 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 20        associate 
21840 74 68 65 20 76 61 6c 75 65 20 56 20 77 69 74 68  the value V with
21850 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74   all SQL paramet
21860 65 72 73 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a  ers having an.**
21870 20 20 20 20 20 20 20 20 20 20 69 6e 64 65 78 20            index 
21880 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b 70 72 65  of N in the [pre
21890 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
218a0 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32   S..**.** {H1352
218b0 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  7} Calls to [sql
218c0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
218d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c   sqlite3_bind(S,
218e0 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  N,...)].**      
218f0 20 20 20 20 6f 76 65 72 72 69 64 65 20 70 72 69      override pri
21900 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 20 74 68  or calls with th
21910 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 6f 66  e same values of
21920 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20   S and N..**.** 
21930 7b 48 31 33 35 33 30 7d 20 42 69 6e 64 69 6e 67  {H13530} Binding
21940 73 20 65 73 74 61 62 6c 69 73 68 65 64 20 62 79  s established by
21950 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
21960 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  ext | sqlite3_bi
21970 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  nd(S,...)].**   
21980 20 20 20 20 20 20 20 70 65 72 73 69 73 74 20 61         persist a
21990 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b  cross calls to [
219a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
219b0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 33  ]..**.** {H13533
219c0 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
219d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
219e0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
219f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
21a00 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
21a10 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
21a20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
21a30 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
21a40 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65  N,V,L,D)] SQLite
21a50 20 62 69 6e 64 73 20 74 68 65 20 66 69 72 73 74   binds the first
21a60 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62   L.**          b
21a70 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42  ytes of the BLOB
21a80 20 6f 72 20 73 74 72 69 6e 67 20 70 6f 69 6e 74   or string point
21a90 65 64 20 74 6f 20 62 79 20 56 2c 20 77 68 65 6e  ed to by V, when
21aa0 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   L.**          i
21ab0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a  s non-negative..
21ac0 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 36 7d 20 49  **.** {H13536} I
21ad0 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
21ae0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
21af0 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20  N,V,L,D)] or.** 
21b00 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
21b10 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
21b20 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65  N,V,L,D)] SQLite
21b30 20 62 69 6e 64 73 20 63 68 61 72 61 63 74 65 72   binds character
21b40 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  s.**          fr
21b50 6f 6d 20 56 20 74 68 72 6f 75 67 68 20 74 68 65  om V through the
21b60 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
21b70 61 63 74 65 72 20 77 68 65 6e 20 4c 20 69 73 20  acter when L is 
21b80 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
21b90 7b 48 31 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c  {H13539} In call
21ba0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
21bb0 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c  nd_blob(S,N,V,L,
21bc0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
21bd0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
21be0 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  ext(S,N,V,L,D)],
21bf0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
21c00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
21c10 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  xt16(S,N,V,L,D)]
21c20 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73   when D is the s
21c30 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20  pecial.**       
21c40 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c     constant [SQL
21c50 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c  ITE_STATIC], SQL
21c60 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
21c70 20 74 68 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20   the value V.** 
21c80 20 20 20 20 20 20 20 20 20 69 73 20 68 65 6c 64           is held
21c90 20 69 6e 20 73 74 61 74 69 63 20 75 6e 6d 61 6e   in static unman
21ca0 61 67 65 64 20 73 70 61 63 65 20 74 68 61 74 20  aged space that 
21cb0 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a  will not change.
21cc0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75 72 69  **          duri
21cd0 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
21ce0 6f 66 20 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a  of the binding..
21cf0 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 32 7d 20 49  **.** {H13542} I
21d00 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
21d10 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
21d20 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20  N,V,L,D)],.**   
21d30 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
21d40 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
21d50 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  L,D)], or.**    
21d60 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
21d70 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
21d80 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73  ,L,D)] when D is
21d90 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20   the special.** 
21da0 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e           constan
21db0 74 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  t [SQLITE_TRANSI
21dc0 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e  ENT], the routin
21dd0 65 20 6d 61 6b 65 73 20 61 0a 2a 2a 20 20 20 20  e makes a.**    
21de0 20 20 20 20 20 20 70 72 69 76 61 74 65 20 63 6f        private co
21df0 70 79 20 6f 66 20 74 68 65 20 76 61 6c 75 65 20  py of the value 
21e00 56 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  V before it retu
21e10 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  rns..**.** {H135
21e20 34 35 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  45} In calls to 
21e30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
21e40 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a  ob(S,N,V,L,D)],.
21e50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
21e60 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
21e70 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a  ,N,V,L,D)], or.*
21e80 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
21e90 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
21ea0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e  S,N,V,L,D)] when
21eb0 20 44 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20   D is a pointer 
21ec0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  to.**          a
21ed0 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
21ee0 65 20 69 6e 76 6f 6b 65 73 20 74 68 61 74 20 66  e invokes that f
21ef0 75 6e 63 74 69 6f 6e 20 74 6f 20 64 65 73 74 72  unction to destr
21f00 6f 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  oy the.**       
21f10 20 20 20 76 61 6c 75 65 20 56 20 61 66 74 65 72     value V after
21f20 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
21f30 20 75 73 69 6e 67 20 74 68 65 20 76 61 6c 75 65   using the value
21f40 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34   V..**.** {H1354
21f50 38 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  8} In calls to [
21f60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
21f70 6f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20  oblob(S,N,V,L)] 
21f80 74 68 65 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a  the value bound.
21f90 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 61  **          is a
21fa0 20 42 4c 4f 42 20 6f 66 20 4c 20 62 79 74 65 73   BLOB of L bytes
21fb0 2c 20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  , or a zero-leng
21fc0 74 68 20 42 4c 4f 42 20 69 66 20 4c 20 69 73 20  th BLOB if L is 
21fd0 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
21fe0 7b 48 31 33 35 35 31 7d 20 49 6e 20 63 61 6c 6c  {H13551} In call
21ff0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
22000 6e 64 5f 76 61 6c 75 65 28 53 2c 4e 2c 56 29 5d  nd_value(S,N,V)]
22010 20 74 68 65 20 56 20 61 72 67 75 6d 65 6e 74 20   the V argument 
22020 6d 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  may.**          
22030 62 65 20 65 69 74 68 65 72 20 61 20 5b 70 72 6f  be either a [pro
22040 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
22050 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6f 72 20  alue] object or 
22060 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
22070 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
22080 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
22090 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
220a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
220b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
220c0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
220d0 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
220e0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
220f0 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
22100 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
22110 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71   double);.int sq
22120 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
22130 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
22140 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  t, int);.int sql
22150 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
22160 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
22170 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
22180 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  4);.int sqlite3_
22190 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
221a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69  3_stmt*, int);.i
221b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
221c0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
221d0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
221e0 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  har*, int n, voi
221f0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
22200 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
22210 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
22220 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
22230 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
22240 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
22250 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
22260 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
22270 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
22280 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
22290 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
222a0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
222b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
222c0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
222d0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
222e0 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b  SQL Parameters {
222f0 48 31 33 36 30 30 7d 20 3c 53 37 30 33 30 30 3e  H13600} <S70300>
22300 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
22310 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
22320 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
22330 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
22340 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
22350 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22360 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
22370 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
22380 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
22390 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
223a0 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
223b0 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
223c0 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
223d0 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
223e0 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
223f0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
22400 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
22410 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
22420 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
22430 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
22440 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
22450 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
22460 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
22470 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
22480 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
22490 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
224a0 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
224b0 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
224c0 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
224d0 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
224e0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
224f0 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  NN are used,.** 
22500 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
22510 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a  s in the list..*
22520 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
22530 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
22540 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
22550 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
22560 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
22570 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
22580 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
22590 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
225a0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
225b0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 30 31 7d  :.**.** {H13601}
225c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   The [sqlite3_bi
225d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
225e0 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  nt(S)] interface
225f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
22600 20 20 20 20 20 74 68 65 20 6c 61 72 67 65 73 74       the largest
22610 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53 51   index of all SQ
22620 4c 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  L parameters in 
22630 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
22640 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22650 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20  ent] S, or 0 if 
22660 53 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  S contains no SQ
22670 4c 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  L parameters..*/
22680 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
22690 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
226a0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
226b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
226c0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
226d0 74 20 50 61 72 61 6d 65 74 65 72 20 7b 48 31 33  t Parameter {H13
226e0 36 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  620} <S70300>.**
226f0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
22700 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
22710 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f  er to the name o
22720 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53  f the n-th.** [S
22730 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
22740 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
22750 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20  tement]..** SQL 
22760 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
22770 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
22780 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
22790 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
227a0 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
227b0 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
227c0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
227d0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
227e0 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
227f0 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
22800 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
22810 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
22820 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
22830 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
22840 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
22850 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f  .** Parameters o
22860 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
22870 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
22880 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
22890 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
228a0 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72 65 64  re also referred
228b0 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75   to as "anonymou
228c0 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
228d0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68  *.** The first h
228e0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
228f0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
22900 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66   not 0..**.** If
22910 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20   the value n is 
22920 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
22930 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61  if the n-th para
22940 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
22950 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
22960 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
22970 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
22980 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
22990 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
229a0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
229b0 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
229c0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
229d0 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
229e0 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
229f0 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
22a00 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
22a10 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
22a20 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
22a30 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
22a40 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
22a50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
22a60 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
22a70 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
22a80 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
22a90 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
22aa0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
22ab0 2a 2a 0a 2a 2a 20 7b 48 31 33 36 32 31 7d 20 54  **.** {H13621} T
22ac0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
22ad0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
22ae0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
22af0 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
22b00 20 20 20 20 61 20 55 54 46 2d 38 20 72 65 6e 64      a UTF-8 rend
22b10 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d  ering of the nam
22b20 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  e of the SQL par
22b30 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20  ameter in.**    
22b40 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
22b50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
22b60 20 68 61 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c   having index N,
22b70 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
22b80 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73  NULL if there is
22b90 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65   no SQL paramete
22ba0 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 6f  r with index N o
22bb0 72 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  r if the.**     
22bc0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 77       parameter w
22bd0 69 74 68 20 69 6e 64 65 78 20 4e 20 69 73 20 61  ith index N is a
22be0 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61  n anonymous para
22bf0 6d 65 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f  meter "?"..*/.co
22c00 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
22c10 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
22c20 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
22c30 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
22c40 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
22c50 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
22c60 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
22c70 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c 53 37 30  me {H13640} <S70
22c80 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  300>.**.** Retur
22c90 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
22ca0 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
22cb0 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
22cc0 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61   The.** index va
22cd0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
22ce0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
22cf0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
22d00 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
22d10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
22d20 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
22d30 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  ].  A zero.** is
22d40 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
22d50 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
22d60 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68  er is found.  Th
22d70 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
22d80 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
22d90 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
22da0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
22db0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
22dc0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
22dd0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
22de0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22df0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
22e00 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
22e10 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
22e20 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
22e30 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
22e40 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
22e50 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
22e60 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
22e70 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
22e80 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
22e90 2a 0a 2a 2a 20 7b 48 31 33 36 34 31 7d 20 54 68  *.** {H13641} Th
22ea0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
22eb0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
22ec0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
22ed0 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
22ee0 20 20 20 20 74 68 65 20 69 6e 64 65 78 20 6f 66      the index of
22ef0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
22f00 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
22f10 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20  statement].**   
22f20 20 20 20 20 20 20 20 53 20 77 68 6f 73 65 20 6e         S whose n
22f30 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68 65 20  ame matches the 
22f40 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20  UTF-8 string N, 
22f50 6f 72 20 30 20 69 66 20 74 68 65 72 65 20 69 73  or 0 if there is
22f60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20  .**          no 
22f70 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71  match..*/.int sq
22f80 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
22f90 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
22fa0 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
22fb0 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
22fc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
22fd0 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
22fe0 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
22ff0 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 36 36  Statement {H1366
23000 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
23010 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68  * Contrary to th
23020 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
23030 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
23040 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
23050 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
23060 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
23070 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
23080 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23090 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68  ment]..** Use th
230a0 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
230b0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
230c0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
230d0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
230e0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 36 31  S:.**.** {H13661
230f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
23100 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 53 29  lear_bindings(S)
23110 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
23120 74 73 20 61 6c 6c 20 53 51 4c 0a 2a 2a 20 20 20  ts all SQL.**   
23130 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
23140 20 62 69 6e 64 69 6e 67 73 20 69 6e 20 74 68 65   bindings in the
23150 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23160 6d 65 6e 74 5d 20 53 20 62 61 63 6b 20 74 6f 20  ment] S back to 
23170 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
23180 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
23190 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
231a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
231b0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
231c0 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
231d0 6c 74 20 53 65 74 20 7b 48 31 33 37 31 30 7d 20  lt Set {H13710} 
231e0 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52  <S10700>.**.** R
231f0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
23200 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
23210 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
23220 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
23230 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23240 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74  ment]. This rout
23250 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
23260 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
23270 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
23280 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
23290 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
232a0 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
232b0 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  )..**.** INVARIA
232c0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  NTS:.**.** {H137
232d0 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
232e0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29  _column_count(S)
232f0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
23300 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
23310 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  f.**          co
23320 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
23330 75 6c 74 20 73 65 74 20 67 65 6e 65 72 61 74 65  ult set generate
23340 64 20 62 79 20 74 68 65 20 5b 70 72 65 70 61 72  d by the [prepar
23350 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c  ed statement] S,
23360 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
23370 30 20 69 66 20 53 20 64 6f 65 73 20 6e 6f 74 20  0 if S does not 
23380 67 65 6e 65 72 61 74 65 20 61 20 72 65 73 75 6c  generate a resul
23390 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  t set..*/.int sq
233a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
233b0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
233c0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
233d0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
233e0 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
233f0 6c 74 20 53 65 74 20 7b 48 31 33 37 32 30 7d 20  lt Set {H13720} 
23400 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10700>.**.** T
23410 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
23420 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
23430 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
23440 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
23450 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
23460 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
23470 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65   statement.  The
23480 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23490 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
234a0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
234b0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
234c0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
234d0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
234e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
234f0 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
23500 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
23510 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
23520 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
23530 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
23540 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
23550 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23560 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
23570 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
23580 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20   statement. The 
23590 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
235a0 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
235b0 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c  n number.  The l
235c0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
235d0 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
235e0 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
235f0 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
23600 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
23610 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
23620 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
23630 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
23640 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
23650 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
23660 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
23670 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
23680 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
23690 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
236a0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
236b0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  olumn..**.** If 
236c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
236d0 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
236e0 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
236f0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
23700 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
23710 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
23720 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
23730 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
23740 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
23750 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
23760 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** The name of a
23770 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
23780 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
23790 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
237a0 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
237b0 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
237c0 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
237d0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
237e0 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
237f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
23800 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
23810 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
23820 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
23830 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
23840 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
23850 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
23860 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 31 7d 20  .**.** {H13721} 
23870 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
23880 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  ocation of the [
23890 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
238a0 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20  ame(S,N)].**    
238b0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
238c0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65  returns the name
238d0 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   of the Nth colu
238e0 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 0a 2a  mn (where 0 is.*
238f0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c  *          the l
23900 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20  eftmost column) 
23910 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74 20 73  for the result s
23920 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  et of the.**    
23930 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
23940 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20  statement] S as 
23950 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
23960 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  d UTF-8 string..
23970 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 33 7d 20 41  **.** {H13723} A
23980 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
23990 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  cation of the [s
239a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
239b0 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20  me16(S,N)].**   
239c0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
239d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d   returns the nam
239e0 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  e of the Nth col
239f0 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 0a  umn (where 0 is.
23a00 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
23a10 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29  leftmost column)
23a20 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74 20   for the result 
23a30 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  set of the.**   
23a40 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
23a50 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73   statement] S as
23a60 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
23a70 65 64 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ed UTF-16 string
23a80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
23a90 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
23aa0 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  order..**.** {H1
23ab0 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  3724} The [sqlit
23ac0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
23ad0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
23ae0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a  olumn_name16()].
23af0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
23b00 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 20  rfaces return a 
23b10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
23b20 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c 65 20  they are unable 
23b30 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  to.**          a
23b40 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
23b50 6f 20 68 6f 6c 64 20 74 68 65 69 72 20 6e 6f 72  o hold their nor
23b60 6d 61 6c 20 72 65 74 75 72 6e 20 73 74 72 69 6e  mal return strin
23b70 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32  gs..**.** {H1372
23b80 35 7d 20 49 66 20 74 68 65 20 4e 20 70 61 72 61  5} If the N para
23b90 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
23ba0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c  3_column_name(S,
23bb0 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  N)] or.**       
23bc0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
23bd0 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  mn_name16(S,N)] 
23be0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
23bf0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   then the.**    
23c00 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
23c10 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70   return a NULL p
23c20 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ointer..**.** {H
23c30 31 33 37 32 36 7d 20 54 68 65 20 73 74 72 69 6e  13726} The strin
23c40 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  gs returned by [
23c50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
23c60 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a  ame(S,N)] and.**
23c70 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
23c80 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
23c90 28 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c 69 64  (S,N)] are valid
23ca0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a   until the next.
23cb0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
23cc0 20 74 6f 20 65 69 74 68 65 72 20 72 6f 75 74 69   to either routi
23cd0 6e 65 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ne with the same
23ce0 20 53 20 61 6e 64 20 4e 20 70 61 72 61 6d 65 74   S and N paramet
23cf0 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
23d00 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
23d10 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69  3_finalize(S)] i
23d20 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  s called..**.** 
23d30 7b 48 31 33 37 32 37 7d 20 57 68 65 6e 20 61 20  {H13727} When a 
23d40 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
23d50 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
23d60 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a  ement contains.*
23d70 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 41 53  *          an AS
23d80 20 63 6c 61 75 73 65 2c 20 74 68 65 20 6e 61 6d   clause, the nam
23d90 65 20 6f 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e  e of that column
23da0 20 69 73 20 74 68 65 20 69 64 65 6e 74 69 66 69   is the identifi
23db0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
23dc0 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66 20 74  o the right of t
23dd0 68 65 20 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a  he AS keyword..*
23de0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
23df0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
23e00 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
23e10 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76   int N);.const v
23e20 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
23e30 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
23e40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
23e50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23e60 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
23e70 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
23e80 75 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c 53 31  ult {H13740} <S1
23e90 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0700>.**.** Thes
23ea0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
23eb0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
23ec0 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c  termine what col
23ed0 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74  umn of what.** t
23ee0 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61  able in which da
23ef0 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20  tabase a result 
23f00 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
23f10 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72  atement comes fr
23f20 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  om..** The name 
23f30 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
23f40 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
23f50 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
23f60 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
23f70 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
23f80 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f  6 string.  The _
23f90 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
23fa0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
23fb0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
23fc0 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
23fd0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
23fe0 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
23ff0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
24000 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
24010 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
24020 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  ** The returned 
24030 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
24040 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
24050 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
24060 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
24070 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
24080 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
24090 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
240a0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
240b0 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
240c0 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
240d0 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  oding..**.** The
240e0 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
240f0 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
24100 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
24110 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
24120 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
24130 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54   column..**.** T
24140 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
24150 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69  t to the followi
24160 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70  ng calls is a [p
24170 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24180 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  t]..** These fun
24190 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
241a0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
241b0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
241c0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
241d0 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
241e0 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
241f0 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
24200 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ment..**.** If t
24210 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
24220 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
24230 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
24240 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
24250 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
24260 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
24270 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
24280 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
24290 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
242a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
242b0 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
242c0 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
242d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
242e0 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74  r.** occurs.  Ot
242f0 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
24300 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
24310 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
24320 74 61 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a  tabase, table.**
24330 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74   and column that
24340 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
24350 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
24360 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41  ed from..**.** A
24370 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
24380 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
24390 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69  ose postfixed wi
243a0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
243b0 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
243c0 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74   strings, the ot
243d0 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
243e0 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44  turn UTF-8. {END
243f0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50  }.**.** These AP
24400 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
24410 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
24420 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
24430 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
24440 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
24450 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
24460 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
24470 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  bol defined..**.
24480 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49  ** {A13751}.** I
24490 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
244a0 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
244b0 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
244c0 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
244d0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
244e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
244f0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
24500 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
24510 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
24520 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
24530 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
24540 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 31 7d 20  .**.** {H13741} 
24550 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
24560 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
24570 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
24580 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
24590 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
245a0 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
245b0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
245c0 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
245d0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20   which the.**   
245e0 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c         Nth resul
245f0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
24600 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24610 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63  ent] S is extrac
24620 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ted,.**         
24630 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
24640 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
24650 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70  is a general exp
24660 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  ression.**      
24670 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65      or if unable
24680 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
24690 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65  ory to store the
246a0 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   name..**.** {H1
246b0 33 37 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  3742} The [sqlit
246c0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
246d0 73 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  se_name16(S,N)] 
246e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
246f0 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
24700 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20       the UTF-16 
24710 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
24720 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  r zero-terminate
24730 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  d name of the da
24740 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20  tabase.**       
24750 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68     from which th
24760 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
24770 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70  umn of the [prep
24780 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24790 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  S is.**         
247a0 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
247b0 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
247c0 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20  olumn of S is a 
247d0 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
247e0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
247f0 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
24800 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
24810 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
24820 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 33 7d  ..**.** {H13743}
24830 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
24840 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
24850 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
24860 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
24870 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55  *          the U
24880 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
24890 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
248a0 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63   table from whic
248b0 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  h the.**        
248c0 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
248d0 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70  umn of the [prep
248e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
248f0 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a  S is extracted,.
24900 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e  **          or N
24910 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
24920 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20  olumn of S is a 
24930 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
24940 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
24950 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
24960 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
24970 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
24980 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 34 7d  ..**.** {H13744}
24990 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
249a0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
249b0 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
249c0 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
249d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
249e0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
249f0 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74  yte order zero-t
24a00 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
24a10 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20  f the table.**  
24a20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 77 68 69          from whi
24a30 63 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ch the Nth resul
24a40 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
24a50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24a60 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20  ent] S is.**    
24a70 20 20 20 20 20 20 65 78 74 72 61 63 74 65 64 2c        extracted,
24a80 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
24a90 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
24aa0 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70  is a general exp
24ab0 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  ression.**      
24ac0 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65      or if unable
24ad0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
24ae0 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65  ory to store the
24af0 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   name..**.** {H1
24b00 33 37 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  3745} The [sqlit
24b10 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
24b20 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _name(S,N)] inte
24b30 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
24b40 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
24b50 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d   the UTF-8 zero-
24b60 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
24b70 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
24b80 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74  umn from which t
24b90 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
24ba0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
24bb0 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
24bc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
24bd0 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20  s extracted,.** 
24be0 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
24bf0 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
24c00 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
24c10 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
24c20 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
24c30 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
24c40 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
24c50 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
24c60 2a 0a 2a 2a 20 7b 48 31 33 37 34 36 7d 20 54 68  *.** {H13746} Th
24c70 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
24c80 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
24c90 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
24ca0 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
24cb0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55  *          the U
24cc0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
24cd0 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72  e order zero-ter
24ce0 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
24cf0 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20  the table.**    
24d00 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 66 72 6f        column fro
24d10 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20  m which the Nth 
24d20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
24d30 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
24d40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24d50 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61  ment] S is extra
24d60 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66  cted, or NULL if
24d70 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 0a   the Nth column.
24d80 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 53  **          of S
24d90 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78   is a general ex
24da0 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
24db0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
24dc0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
24dd0 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
24de0 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e name..**.** {H
24df0 31 33 37 34 38 7d 20 54 68 65 20 72 65 74 75 72  13748} The retur
24e00 6e 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a  n values from.**
24e10 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
24e20 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
24e30 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
24e40 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
24e50 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20  aces].**        
24e60 20 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20    are valid for 
24e70 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20  the lifetime of 
24e80 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24e90 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20  atement].**     
24ea0 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 74 68       or until th
24eb0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 63 68  e encoding is ch
24ec0 61 6e 67 65 64 20 62 79 20 61 6e 6f 74 68 65 72  anged by another
24ed0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20   metadata.**    
24ee0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
24ef0 63 61 6c 6c 20 66 6f 72 20 74 68 65 20 73 61 6d  call for the sam
24f00 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
24f10 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ment and column.
24f20 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
24f30 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35  NS:.**.** {A1375
24f40 31 7d 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  1} If two or mor
24f50 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
24f60 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20  ne or more.**   
24f70 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
24f80 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
24f90 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
24fa0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
24fb0 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  s].**          f
24fc0 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
24fd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24fe0 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
24ff0 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  mn.**          a
25000 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
25010 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
25020 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
25030 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
25040 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
25050 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
25060 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
25070 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
25080 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
25090 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
250a0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
250b0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
250c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
250d0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
250e0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
250f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
25100 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
25110 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
25120 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
25130 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
25140 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
25150 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
25160 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
25170 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
25180 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
25190 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
251a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
251b0 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
251c0 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
251d0 74 20 7b 48 31 33 37 36 30 7d 20 3c 53 31 30 37  t {H13760} <S107
251e0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  00>.**.** The fi
251f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
25200 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
25210 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
25220 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
25230 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
25240 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
25250 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
25260 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
25270 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
25280 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
25290 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
252a0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
252b0 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
252c0 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
252d0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
252e0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
252f0 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20  turned.  If the 
25300 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
25310 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
25320 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
25330 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
25340 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
25350 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
25360 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
25370 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
25380 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b  UTF-8 encoded. {
25390 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  END}.**.** For e
253a0 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
253b0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
253c0 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
253d0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
253e0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
253f0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
25400 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
25410 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
25420 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
25430 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
25440 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
25450 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
25460 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
25470 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
25480 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
25490 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
254a0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
254b0 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
254c0 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a  lumn (i==0)..**.
254d0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  ** SQLite uses d
254e0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
254f0 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74  typing.  So just
25500 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
25510 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
25520 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
25530 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
25540 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
25550 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
25560 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
25570 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
25580 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
25590 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
255a0 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
255b0 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
255c0 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
255d0 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f   Type.** is asso
255e0 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
255f0 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
25600 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
25610 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
25620 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
25630 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ues..**.** INVAR
25640 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
25650 33 37 36 31 7d 20 20 41 20 73 75 63 63 65 73 73  3761}  A success
25660 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
25670 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
25680 74 79 70 65 28 53 2c 4e 29 5d 20 72 65 74 75 72  type(S,N)] retur
25690 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  ns a.**         
256a0 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
256b0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63  d UTF-8 string c
256c0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65  ontaining the de
256d0 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 0a  clared datatype.
256e0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 20  **           of 
256f0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
25700 20 74 68 61 74 20 61 70 70 65 61 72 73 20 61 73   that appears as
25710 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
25720 28 6e 75 6d 62 65 72 65 64 0a 2a 2a 20 20 20 20  (numbered.**    
25730 20 20 20 20 20 20 20 66 72 6f 6d 20 30 29 20 6f         from 0) o
25740 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
25750 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
25760 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
25770 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 32 7d 20 20  **.** {H13762}  
25780 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
25790 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
257a0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
257b0 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,N)].**        
257c0 20 20 20 72 65 74 75 72 6e 73 20 61 20 7a 65 72     returns a zer
257d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
257e0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
257f0 6f 72 64 65 72 20 73 74 72 69 6e 67 0a 2a 2a 20  order string.** 
25800 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 61 69            contai
25810 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65  ning the declare
25820 64 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68  d datatype of th
25830 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
25840 68 61 74 20 61 70 70 65 61 72 73 0a 2a 2a 20 20  hat appears.**  
25850 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20           as the 
25860 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62  Nth column (numb
25870 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f 66 20  ered from 0) of 
25880 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 74  the result set t
25890 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
258a0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
258b0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a  tement] S..**.**
258c0 20 7b 48 31 33 37 36 33 7d 20 20 49 66 20 4e 20   {H13763}  If N 
258d0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 30 20 6f  is less than 0 o
258e0 72 20 4e 20 69 73 20 67 72 65 61 74 65 72 20 74  r N is greater t
258f0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 0a  han or equal to.
25900 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65  **           the
25910 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
25920 6e 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  ns in the [prepa
25930 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
25940 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  ,.**           o
25950 72 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  r if the Nth col
25960 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65  umn of S is an e
25970 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
25980 71 75 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20  query rather.** 
25990 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 61            than a
259a0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20 6f   table column, o
259b0 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
259c0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
259d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63  .**           oc
259e0 63 75 72 73 20 64 75 72 69 6e 67 20 65 6e 63 6f  curs during enco
259f0 64 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73  ding conversions
25a00 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
25a10 20 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71      calls to [sq
25a20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
25a30 6c 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a  ltype(S,N)] or.*
25a40 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
25a50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
25a60 74 79 70 65 31 36 28 53 2c 4e 29 5d 20 72 65 74  type16(S,N)] ret
25a70 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e  urn NULL..*/.con
25a80 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
25a90 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
25aa0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
25ab0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
25ac0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
25ad0 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
25ae0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
25af0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25b00 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
25b10 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 32 30  Statement {H1320
25b20 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S10000>.**.*
25b30 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
25b40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
25b50 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
25b60 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
25b70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25b80 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
25b90 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
25ba0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
25bb0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
25bc0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
25bd0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
25be0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25bf0 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
25c00 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
25c10 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
25c20 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
25c30 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
25c40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
25c50 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
25c60 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
25c70 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
25c80 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
25c90 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
25ca0 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
25cb0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
25cc0 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
25cd0 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
25ce0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
25cf0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25d00 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
25d10 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
25d20 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
25d30 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
25d40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
25d50 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
25d60 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
25d70 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
25d80 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
25d90 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
25da0 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
25db0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
25dc0 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
25dd0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
25de0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61  *.** In the lega
25df0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
25e00 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
25e10 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
25e20 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
25e30 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
25e40 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
25e50 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
25e60 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
25e70 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 32  .** With the "v2
25e80 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
25e90 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
25ea0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
25eb0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
25ec0 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
25ed0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
25ee0 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  well..**.** [SQL
25ef0 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20  ITE_BUSY] means 
25f00 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
25f10 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61  e engine was una
25f20 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74  ble to acquire t
25f30 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c  he.** database l
25f40 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f  ocks it needs to
25f50 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66   do its job.  If
25f60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
25f70 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
25f80 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
25f90 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
25fa0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
25fb0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
25fc0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
25fd0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
25fe0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
25ff0 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
26000 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78  s within a.** ex
26010 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
26020 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
26030 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
26040 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
26050 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
26060 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
26070 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
26080 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
26090 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
260a0 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
260b0 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
260c0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
260d0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
260e0 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
260f0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
26100 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
26110 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
26120 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
26130 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
26140 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
26150 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
26160 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
26170 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
26180 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
26190 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
261a0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
261b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
261c0 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
261d0 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
261e0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
261f0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
26200 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
26210 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
26220 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
26230 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
26240 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
26250 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
26260 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
26270 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
26280 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51   data..**.** [SQ
26290 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
262a0 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
262b0 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
262c0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
262d0 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
262e0 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
262f0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
26300 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
26310 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
26320 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
26330 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
26340 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
26350 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
26360 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67 61  ** With the lega
26370 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
26380 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
26390 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
263a0 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
263b0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
263c0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
263d0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
263e0 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
263f0 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
26400 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
26410 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
26420 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
26430 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
26440 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
26450 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
26460 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
26470 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
26480 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
26490 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
264a0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
264b0 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
264c0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
264d0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
264e0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
264f0 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
26500 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
26510 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26520 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
26530 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
26540 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
26550 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
26560 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
26570 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
26580 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
26590 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
265a0 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
265b0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
265c0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
265d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
265e0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
265f0 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
26600 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
26610 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
26620 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ime..**.** <b>Go
26630 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
26640 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
26650 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
26660 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
26670 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
26680 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
26690 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
266a0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
266b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
266c0 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
266d0 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
266e0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
266f0 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
26700 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
26710 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
26720 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
26730 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
26740 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
26750 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
26760 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
26770 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
26780 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
26790 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
267a0 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
267b0 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
267c0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
267d0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
267e0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
267f0 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
26800 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
26810 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
26820 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
26830 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
26840 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26850 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
26860 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
26870 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26880 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
26890 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
268a0 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
268b0 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
268c0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
268d0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
268e0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
268f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
26900 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
26910 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
26920 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
26930 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
26940 2a 2a 0a 2a 2a 20 7b 48 31 33 32 30 32 7d 20 20  **.** {H13202}  
26950 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  If the [prepared
26960 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
26970 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 75 6e   ready to be run
26980 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
26990 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65      [sqlite3_ste
269a0 70 28 53 29 5d 20 61 64 76 61 6e 63 65 73 20 74  p(S)] advances t
269b0 68 61 74 20 70 72 65 70 61 72 65 64 20 73 74 61  hat prepared sta
269c0 74 65 6d 65 6e 74 20 75 6e 74 69 6c 0a 2a 2a 20  tement until.** 
269d0 20 20 20 20 20 20 20 20 20 20 63 6f 6d 70 6c 65            comple
269e0 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74  tion or until it
269f0 20 69 73 20 72 65 61 64 79 20 74 6f 20 72 65 74   is ready to ret
26a00 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  urn another row 
26a10 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
26a20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 2c 20      result set, 
26a30 6f 72 20 75 6e 74 69 6c 20 61 6e 20 5b 73 71 6c  or until an [sql
26a40 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c  ite3_interrupt |
26a50 20 69 6e 74 65 72 72 75 70 74 5d 0a 2a 2a 20 20   interrupt].**  
26a60 20 20 20 20 20 20 20 20 20 6f 72 20 61 20 72 75           or a ru
26a70 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f 63 63  n-time error occ
26a80 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33  urs..**.** {H153
26a90 30 34 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c  04}  When a call
26aa0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
26ab0 70 28 53 29 5d 20 63 61 75 73 65 73 20 74 68 65  p(S)] causes the
26ac0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26ad0 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ment].**        
26ae0 20 20 20 53 20 74 6f 20 72 75 6e 20 74 6f 20 63     S to run to c
26af0 6f 6d 70 6c 65 74 69 6f 6e 2c 20 74 68 65 20 66  ompletion, the f
26b00 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
26b10 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a  [SQLITE_DONE]..*
26b20 2a 0a 2a 2a 20 7b 48 31 35 33 30 36 7d 20 20 57  *.** {H15306}  W
26b30 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  hen a call to [s
26b40 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
26b50 73 74 6f 70 73 20 62 65 63 61 75 73 65 20 69 74  stops because it
26b60 20 69 73 20 72 65 61 64 79 20 74 6f 0a 2a 2a 20   is ready to.** 
26b70 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
26b80 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20   another row of 
26b90 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2c 20  the result set, 
26ba0 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
26bb0 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  TE_ROW]..**.** {
26bc0 48 31 35 33 30 38 7d 20 20 49 66 20 61 20 63 61  H15308}  If a ca
26bd0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
26be0 74 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65  tep(S)] encounte
26bf0 72 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  rs an.**        
26c00 20 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65     [sqlite3_inte
26c10 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70  rrupt | interrup
26c20 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65  t] or a run-time
26c30 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20   error,.**      
26c40 20 20 20 20 20 69 74 20 72 65 74 75 72 6e 73 20       it returns 
26c50 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
26c60 72 72 6f 72 20 63 6f 64 65 20 74 68 61 74 20 69  rror code that i
26c70 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20  s not one of.** 
26c80 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
26c90 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  E_OK], [SQLITE_R
26ca0 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OW], or [SQLITE_
26cb0 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  DONE]..**.** {H1
26cc0 35 33 31 30 7d 20 20 49 66 20 61 6e 20 5b 73 71  5310}  If an [sq
26cd0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20  lite3_interrupt 
26ce0 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20  | interrupt] or 
26cf0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
26d00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63  .**           oc
26d10 63 75 72 73 20 64 75 72 69 6e 67 20 61 20 63 61  curs during a ca
26d20 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
26d30 74 65 70 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20  tep(S)].**      
26d40 20 20 20 20 20 66 6f 72 20 61 20 5b 70 72 65 70       for a [prep
26d50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26d60 53 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  S created using.
26d70 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6c 65 67  **           leg
26d80 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b  acy interfaces [
26d90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
26da0 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
26db0 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
26dc0 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74  are16()], then t
26dd0 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
26de0 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
26df0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
26e00 45 52 52 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERROR], [SQLITE_
26e10 42 55 53 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BUSY], or [SQLIT
26e20 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e  E_MISUSE]..*/.in
26e30 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
26e40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
26e50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26e60 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
26e70 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
26e80 74 20 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 37  t {H13770} <S107
26e90 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  00>.**.** Return
26ea0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
26eb0 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75  values in the cu
26ec0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
26ed0 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a   result set..**.
26ee0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
26ef0 2a 0a 2a 2a 20 7b 48 31 33 37 37 31 7d 20 20 41  *.** {H13771}  A
26f00 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b  fter a call to [
26f10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
26f20 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 5b 53   that returns [S
26f30 51 4c 49 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 20  QLITE_ROW],.**  
26f40 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
26f50 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
26f60 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 77 69 6c  (S)] routine wil
26f70 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  l return the sam
26f80 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20  e value.**      
26f90 20 20 20 20 20 61 73 20 74 68 65 20 5b 73 71 6c       as the [sql
26fa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
26fb0 74 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a  t(S)] function..
26fc0 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37 32 7d 20 20  **.** {H13772}  
26fd0 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  After [sqlite3_s
26fe0 74 65 70 28 53 29 5d 20 68 61 73 20 72 65 74 75  tep(S)] has retu
26ff0 72 6e 65 64 20 61 6e 79 20 76 61 6c 75 65 20 6f  rned any value o
27000 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
27010 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52         [SQLITE_R
27020 4f 57 5d 20 6f 72 20 62 65 66 6f 72 65 20 5b 73  OW] or before [s
27030 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
27040 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
27050 6f 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  on the.**       
27060 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
27070 61 74 65 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65  atement] for the
27080 20 66 69 72 73 74 20 74 69 6d 65 20 73 69 6e 63   first time sinc
27090 65 20 69 74 20 77 61 73 0a 2a 2a 20 20 20 20 20  e it was.**     
270a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
270b0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
270c0 64 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  d] or [sqlite3_r
270d0 65 73 65 74 20 7c 20 72 65 73 65 74 5d 2c 0a 2a  eset | reset],.*
270e0 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20  *           the 
270f0 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
27100 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 20  unt(S)] routine 
27110 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f  returns zero..*/
27120 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
27130 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
27140 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
27150 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
27160 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
27170 79 70 65 73 20 7b 48 31 30 32 36 35 7d 20 3c 53  ypes {H10265} <S
27180 31 30 31 31 30 3e 3c 53 31 30 31 32 30 3e 0a 2a  10110><S10120>.*
27190 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
271a0 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48  TE_TEXT.**.** {H
271b0 31 30 32 36 36 7d 20 45 76 65 72 79 20 76 61 6c  10266} Every val
271c0 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
271d0 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
271e0 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
271f0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
27200 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
27210 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
27220 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
27230 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
27240 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
27250 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
27260 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
27270 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a  ** </ul> {END}.*
27280 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
27290 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
272a0 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
272b0 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
272c0 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
272d0 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
272e0 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
272f0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
27300 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
27310 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
27320 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
27330 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
27340 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
27350 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
27360 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
27370 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
27380 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
27390 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
273a0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
273b0 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
273c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
273d0 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
273e0 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
273f0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
27400 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
27410 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
27420 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
27430 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
27440 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
27450 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
27460 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
27470 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
27480 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
27490 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
274a0 72 79 20 7b 48 31 33 38 30 30 7d 20 3c 53 31 30  ry {H13800} <S10
274b0 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  700>.** KEYWORDS
274c0 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
274d0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
274e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
274f0 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c   form the "resul
27500 74 20 73 65 74 20 71 75 65 72 79 22 20 69 6e 74  t set query" int
27510 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
27520 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
27530 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
27540 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
27550 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
27560 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
27570 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
27580 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
27590 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
275a0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
275b0 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
275c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
275d0 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
275e0 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
275f0 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
27600 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
27610 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
27620 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
27630 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
27640 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
27650 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
27660 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
27670 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
27680 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
27690 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
276a0 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74 6d  rned.  The leftm
276b0 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
276c0 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
276d0 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
276e0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
276f0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
27700 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
27710 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
27720 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
27730 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
27740 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
27750 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
27760 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
27770 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
27780 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
27790 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
277a0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
277b0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
277c0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
277d0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
277e0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
277f0 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
27800 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
27810 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
27820 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
27830 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
27840 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
27850 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
27860 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
27870 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
27880 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
27890 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
278a0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
278b0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
278c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
278d0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
278e0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
278f0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
27900 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
27910 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
27920 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
27930 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
27940 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
27950 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
27960 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
27970 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
27980 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
27990 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
279a0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
279b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
279c0 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
279d0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
279e0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
279f0 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
27a00 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
27a10 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
27a20 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
27a30 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  .  The returned 
27a40 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
27a50 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
27a60 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
27a70 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
27a80 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
27a90 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
27aa0 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
27ab0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
27ac0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
27ad0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
27ae0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
27af0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
27b00 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
27b10 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
27b20 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
27b30 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
27b40 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
27b50 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
27b60 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
27b70 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
27b80 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
27b90 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
27ba0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
27bb0 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
27bc0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
27bd0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
27be0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
27bf0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
27c00 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
27c10 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
27c20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27c30 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
27c40 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
27c50 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
27c60 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
27c70 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65  tring..** If the
27c80 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
27c90 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
27ca0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27cb0 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
27cc0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
27cd0 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
27ce0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
27cf0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
27d00 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
27d10 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
27d20 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
27d30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
27d40 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
27d50 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
27d60 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
27d70 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
27d80 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
27d90 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
27da0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
27db0 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c  ring..** The val
27dc0 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  ue returned does
27dd0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
27de0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
27df0 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
27e00 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46  f the string.  F
27e10 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
27e20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
27e30 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
27e40 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
27e50 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
27e60 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
27e70 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69  ters..**.** Stri
27e80 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
27e90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27ea0 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
27eb0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
27ec0 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
27ed0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
27ee0 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e  ways zero termin
27ef0 61 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 72  ated.  The retur
27f00 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
27f10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27f20 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
27f30 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
27f40 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  an arbitrary.** 
27f50 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c  pointer, possibl
27f60 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  y even a NULL po
27f70 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
27f80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27f90 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e  bytes16() routin
27fa0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
27fb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27fc0 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65  ytes().** but le
27fd0 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  aves the result 
27fe0 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  in UTF-16 in nat
27ff0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
28000 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e  nstead of UTF-8.
28010 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72  .** The zero ter
28020 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69  minator is not i
28030 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20  ncluded in this 
28040 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  count..**.** The
28050 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
28060 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
28070 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
28080 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
28090 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
280a0 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
280b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
280c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
280d0 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
280e0 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
280f0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
28100 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
28110 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
28120 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
28130 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28140 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
28150 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
28160 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
28170 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
28180 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
28190 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
281a0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
281b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
281c0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
281d0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
281e0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
281f0 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
28200 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
28210 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
28220 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
28230 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
28240 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
28250 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
28260 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
28270 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
28280 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
28290 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
282a0 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
282b0 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
282c0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
282d0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
282e0 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
282f0 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
28300 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
28310 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  y.  The followin
28320 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
28330 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
28340 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
28350 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
28360 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
28370 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
28380 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
28390 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
283a0 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
283b0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
283c0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
283d0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
283e0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
283f0 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
28400 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
28410 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
28420 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
28430 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
28440 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
28450 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
28460 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
28470 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
28480 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
28490 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
284a0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
284b0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
284c0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
284d0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
284e0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
284f0 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
28500 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
28510 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
28520 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
28530 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
28540 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
28550 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
28560 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
28570 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
28580 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
28590 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
285a0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
285b0 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69   from float to i
285c0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
285d0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
285e0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
285f0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
28600 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
28610 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
28620 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
28630 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c   <td> Same as FL
28640 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  OAT->TEXT.** <tr
28650 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
28660 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
28670 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a  d> Use atoi().**
28680 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
28690 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
286a0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28    <td> Use atof(
286b0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
286c0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
286d0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
286e0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
286f0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
28700 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
28710 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
28720 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a  en use atoi().**
28730 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
28740 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
28750 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
28760 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
28770 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
28780 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
28790 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
287a0 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
287b0 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
287c0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
287d0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
287e0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f  ** The table abo
287f0 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e  ve makes referen
28800 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43  ce to standard C
28810 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f   library functio
28820 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64  ns atoi().** and
28830 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65   atof().  SQLite
28840 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79   does not really
28850 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74   use these funct
28860 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74  ions.  It has it
28870 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c  s.** own equival
28880 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
28890 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
288a0 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
288b0 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
288c0 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
288d0 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
288e0 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
288f0 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
28900 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
28910 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
28920 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
28930 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
28940 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
28950 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
28960 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
28970 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
28980 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
28990 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
289a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
289b0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
289c0 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
289d0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
289e0 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
289f0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
28a00 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
28a10 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
28a20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
28a30 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
28a40 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
28a50 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
28a60 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
28a70 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
28a80 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
28a90 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
28aa0 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
28ab0 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
28ac0 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
28ad0 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
28ae0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
28af0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
28b00 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
28b10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
28b20 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
28b30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
28b40 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
28b50 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
28b60 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
28b70 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
28b80 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
28b90 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
28ba0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
28bb0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
28bc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
28bd0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
28be0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
28bf0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
28c00 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
28c10 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
28c20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
28c30 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
28c40 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
28c50 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
28c60 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
28c70 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
28c80 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
28c90 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
28ca0 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
28cb0 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
28cc0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
28cd0 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
28ce0 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
28cf0 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c  r points to will
28d00 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
28d10 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
28d20 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
28d30 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
28d40 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
28d50 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
28d60 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
28d70 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
28d80 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
28d90 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
28da0 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
28db0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
28dc0 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
28dd0 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
28de0 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
28df0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
28e00 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
28e10 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
28e20 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
28e30 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
28e40 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
28e50 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
28e60 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
28e70 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
28e80 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
28e90 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
28ea0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28eb0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
28ec0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28ed0 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
28ee0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
28ef0 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
28f00 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
28f10 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
28f20 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
28f30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28f40 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
28f50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
28f60 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
28f70 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
28f80 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
28f90 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
28fa0 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
28fb0 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
28fc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28fd0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
28fe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28ff0 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
29000 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
29010 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
29020 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
29030 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29040 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
29050 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
29060 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
29070 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
29080 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
29090 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
290a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
290b0 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
290c0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
290d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
290e0 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
290f0 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
29100 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
29110 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
29120 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
29130 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
29140 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
29150 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
29160 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
29170 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
29180 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
29190 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61    The memory spa
291a0 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
291b0 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
291c0 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
291d0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
291e0 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
291f0 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
29200 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74  turned.** [sqlit
29210 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
29220 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
29230 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
29240 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
29250 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
29260 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   If a memory all
29270 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
29280 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
29290 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
292a0 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
292b0 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
292c0 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
292d0 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
292e0 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
292f0 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
29300 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
29310 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
29320 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
29330 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
29340 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
29350 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
29360 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
29370 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
29380 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
29390 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 33  S:.**.** {H13803
293a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
293b0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d  olumn_blob(S,N)]
293c0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
293d0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
293e0 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
293f0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
29400 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
29410 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
29420 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65      the [prepare
29430 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
29440 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20 74  nto a BLOB and t
29450 68 65 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a  hen returns a.**
29460 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65            pointe
29470 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74  r to the convert
29480 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ed value..**.** 
29490 7b 48 31 33 38 30 36 7d 20 54 68 65 20 5b 73 71  {H13806} The [sq
294a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
294b0 65 73 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  es(S,N)] interfa
294c0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ce returns the.*
294d0 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
294e0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
294f0 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
29500 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74   (exclusive of t
29510 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  he.**          z
29520 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f  ero terminator o
29530 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68  n the string) th
29540 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
29550 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
29560 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63     most recent c
29570 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
29580 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29  column_blob(S,N)
29590 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
295a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
295b0 5f 74 65 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a  _text(S,N)]..**.
295c0 2a 2a 20 7b 48 31 33 38 30 39 7d 20 54 68 65 20  ** {H13809} The 
295d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
295e0 62 79 74 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e  bytes16(S,N)] in
295f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
29600 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29610 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
29620 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28 65  in the string (e
29630 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a  xclusive of the.
29640 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
29650 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74   terminator on t
29660 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20  he string) that 
29670 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  was returned by 
29680 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29690 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
296a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
296b0 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d  umn_text16(S,N)]
296c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 32 7d  ..**.** {H13812}
296d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
296e0 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29  lumn_double(S,N)
296f0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
29700 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
29710 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
29720 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
29730 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
29740 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20   set for the.** 
29750 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
29760 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
29770 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20  into a floating 
29780 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a  point value and.
29790 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
297a0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
297b0 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  at value..**.** 
297c0 7b 48 31 33 38 31 35 7d 20 54 68 65 20 5b 73 71  {H13815} The [sq
297d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
297e0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
297f0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
29800 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
29810 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
29820 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
29830 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68  esult set for th
29840 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
29850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29860 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62  t] S into a 64-b
29870 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
29880 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  r and.**        
29890 20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f    returns the lo
298a0 77 65 72 20 33 32 20 62 69 74 73 20 6f 66 20 74  wer 32 bits of t
298b0 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  hat integer..**.
298c0 2a 2a 20 7b 48 31 33 38 31 38 7d 20 54 68 65 20  ** {H13818} The 
298d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
298e0 69 6e 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65  int64(S,N)] inte
298f0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
29900 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
29910 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
29920 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
29930 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
29940 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
29950 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
29960 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
29970 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
29980 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
29990 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
299a0 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e   copy of that in
299b0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  teger..**.** {H1
299c0 33 38 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3821} The [sqlit
299d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53  e3_column_text(S
299e0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
299f0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
29a00 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
29a10 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
29a20 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
29a30 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
29a40 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65          the [pre
29a50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29a60 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   S into a zero-t
29a70 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
29a80 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
29a90 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
29aa0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
29ab0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
29ac0 48 31 33 38 32 34 7d 20 54 68 65 20 5b 73 71 6c  H13824} The [sql
29ad0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29ae0 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
29af0 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
29b00 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
29b10 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
29b20 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
29b30 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20   result set for 
29b40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29b50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29b60 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65  ent] S into a ze
29b70 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d  ro-terminated 2-
29b80 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  byte.**         
29b90 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20   aligned UTF-16 
29ba0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
29bb0 72 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  r string and ret
29bc0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
29bd0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
29be0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
29bf0 20 7b 48 31 33 38 32 37 7d 20 54 68 65 20 5b 73   {H13827} The [s
29c00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
29c10 70 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  pe(S,N)] interfa
29c20 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
29c30 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53         one of [S
29c40 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51  QLITE_NULL], [SQ
29c50 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b  LITE_INTEGER], [
29c60 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a  SQLITE_FLOAT],.*
29c70 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
29c80 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51  TE_TEXT], or [SQ
29c90 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70  LITE_BLOB] as ap
29ca0 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a  propriate for.**
29cb0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 4e 74            the Nt
29cc0 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
29cd0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
29ce0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
29cf0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
29d00 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29d10 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20  ement] S..**.** 
29d20 7b 48 31 33 38 33 30 7d 20 54 68 65 20 5b 73 71  {H13830} The [sq
29d30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
29d40 75 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ue(S,N)] interfa
29d50 63 65 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20  ce returns a.** 
29d60 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72           pointer
29d70 20 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   to an [unprotec
29d80 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29d90 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20 74 68  e] object for th
29da0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
29db0 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
29dc0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
29dd0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
29de0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
29df0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29e00 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e  ement] S..*/.con
29e10 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
29e20 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
29e30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
29e40 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
29e50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
29e60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29e70 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
29e80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
29e90 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
29ea0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
29eb0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
29ec0 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
29ed0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
29ee0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
29ef0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
29f00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
29f10 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
29f20 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
29f30 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
29f40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
29f50 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
29f60 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
29f70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
29f80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
29f90 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
29fa0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
29fb0 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
29fc0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
29fd0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
29fe0 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
29ff0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2a000 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
2a010 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
2a020 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
2a030 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2a040 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a050 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
2a060 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2a070 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 30 30 7d   Object {H13300}
2a080 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 31 30 30   <S70300><S30100
2a090 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
2a0a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
2a0b0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
2a0c0 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
2a0d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a0e0 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 74  t]..** If the st
2a0f0 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63  atement was exec
2a100 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  uted successfull
2a110 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65  y or not execute
2a120 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a  d at all, then.*
2a130 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  * SQLITE_OK is r
2a140 65 74 75 72 6e 65 64 2e 20 49 66 20 65 78 65 63  eturned. If exec
2a150 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ution of the sta
2a160 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68  tement failed th
2a170 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  en an.** [error 
2a180 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
2a190 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
2a1a0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2a1b0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
2a1c0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
2a1d0 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
2a1e0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
2a1f0 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
2a200 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
2a210 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d  If the virtual m
2a220 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a  achine has not.*
2a230 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
2a240 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20  ution when this 
2a250 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
2a260 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a  d, that is like.
2a270 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  ** encountering 
2a280 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b  an error or an [
2a290 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
2a2a0 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a  t | interrupt]..
2a2b0 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70  ** Incomplete up
2a2c0 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c  dates may be rol
2a2d0 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61  led back and tra
2a2e0 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c  nsactions cancel
2a2f0 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67  ed,.** depending
2a300 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74   on the circumst
2a310 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a  ances, and the.*
2a320 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72  * [error code] r
2a330 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20  eturned will be 
2a340 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
2a350 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2a360 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 32 7d  :.**.** {H11302}
2a370 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   The [sqlite3_fi
2a380 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e 74 65 72  nalize(S)] inter
2a390 66 61 63 65 20 64 65 73 74 72 6f 79 73 20 74 68  face destroys th
2a3a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2a3b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a3c0 74 5d 20 53 20 61 6e 64 20 72 65 6c 65 61 73 65  t] S and release
2a3d0 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  s all.**        
2a3e0 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 66 69 6c    memory and fil
2a3f0 65 20 72 65 73 6f 75 72 63 65 73 20 68 65 6c 64  e resources held
2a400 20 62 79 20 74 68 61 74 20 6f 62 6a 65 63 74 2e   by that object.
2a410 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 34 7d 20  .**.** {H11304} 
2a420 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2a430 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2a440 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2a450 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2a460 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a470 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
2a480 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20   an error,.**   
2a490 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
2a4a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2a4b0 5d 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 73  ] returns that s
2a4c0 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e  ame error..*/.in
2a4d0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
2a4e0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
2a4f0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2a500 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2a510 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2a520 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33  ment Object {H13
2a530 33 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  330} <S70300>.**
2a540 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2a550 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
2a560 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
2a570 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
2a580 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2a590 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
2a5a0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
2a5b0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
2a5c0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  xecuted..** Any 
2a5d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
2a5e0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
2a5f0 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
2a600 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
2a610 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2a620 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2a630 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
2a640 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
2a650 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
2a660 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2a670 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
2a680 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
2a690 2a 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b  * {H11332} The [
2a6a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2a6b0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
2a6c0 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
2a6d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
2a6e0 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74            back t
2a6f0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
2a700 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
2a710 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49  **.** {H11334} I
2a720 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2a730 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2a740 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2a750 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2a760 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a770 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
2a780 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
2a790 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
2a7a0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
2a7b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2a7c0 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
2a7d0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
2a7e0 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20  on S,.**        
2a7f0 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
2a800 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
2a810 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
2a820 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66  *.** {H11336} If
2a830 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2a840 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2a850 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2a860 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2a870 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a880 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
2a890 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
2a8a0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2a8b0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2a8c0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
2a8d0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2a8e0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38  ]..**.** {H11338
2a8f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2a900 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
2a910 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
2a920 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
2a930 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79            of any
2a940 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2a950 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
2a960 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a970 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
2a980 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
2a990 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2a9a0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2a9b0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
2a9c0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
2a9d0 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 30  Functions {H1610
2a9e0 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b  0} <S20200>.** K
2a9f0 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
2aa00 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
2aa10 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
2aa20 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2aa30 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2aa40 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
2aa50 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2aa60 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2aa70 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
2aa80 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  se two functions
2aa90 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
2aaa0 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
2aab0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2aac0 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
2aad0 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
2aae0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2aaf0 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
2ab00 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
2ab10 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
2ab20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2ab30 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
2ab40 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
2ab50 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a  e between the.**
2ab60 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65   two is that the
2ab70 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2ab80 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r, the name of t
2ab90 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63  he (scalar) func
2aba0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2abb0 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64  gate, is encoded
2abc0 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71   in UTF-8 for sq
2abd0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2abe0 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d  ction() and UTF-
2abf0 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  16.** for sqlite
2ac00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2ac10 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  n16()..**.** The
2ac20 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2ac30 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
2ac40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
2ac50 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
2ac60 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
2ac70 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 61   be added.  If a
2ac80 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20   single program 
2ac90 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
2aca0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
2acb0 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e  onnection intern
2acc0 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 66  ally, then SQL f
2acd0 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
2ace0 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61   added individua
2acf0 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64  lly to.** each d
2ad00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ad10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  on..**.** The se
2ad20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2ad30 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
2ad40 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
2ad50 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
2ad60 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 54  ** redefined.  T
2ad70 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
2ad80 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
2ad90 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65   to 255 bytes, e
2ada0 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74  xclusive of.** t
2adb0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
2adc0 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  or.  Note that t
2add0 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c  he name length l
2ade0 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73  imit is in bytes
2adf0 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74  , not.** charact
2ae00 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70  ers.  Any attemp
2ae10 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
2ae20 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
2ae30 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
2ae40 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
2ae50 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67  ITE_ERROR] being
2ae60 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2ae70 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
2ae80 65 74 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62  eter is the numb
2ae90 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2aea0 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
2aeb0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2aec0 65 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20  egate takes. If 
2aed0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
2aee0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2aef0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2af00 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2af10 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
2af20 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2af30 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ts..**.** The fo
2af40 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
2af50 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
2af60 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c  ies what.** [SQL
2af70 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
2af80 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
2af90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
2afa0 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
2afb0 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20  arameters.  Any 
2afc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
2afd0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
2afe0 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f  ld be able to wo
2aff0 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20  rk.** work with 
2b000 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
2b010 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
2b020 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
2b030 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
2b040 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
2b050 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
2b060 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
2b070 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20    It is allowed 
2b080 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
2b090 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b0a0 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
2b0b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b0c0 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
2b0d0 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
2b0e0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
2b0f0 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
2b100 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
2b110 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75  tRep..** When mu
2b120 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2b130 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2b140 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
2b150 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
2b160 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
2b170 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
2b180 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
2b190 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
2b1a0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20  nversion..** If 
2b1b0 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20  there is only a 
2b1c0 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  single implement
2b1d0 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73  ation which does
2b1e0 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74   not care what t
2b1f0 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20  ext.** encoding 
2b200 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  is used, then th
2b210 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
2b220 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c  t should be [SQL
2b230 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20  ITE_ANY]..**.** 
2b240 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
2b250 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
2b260 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
2b270 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2b280 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
2b290 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
2b2a0 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
2b2b0 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
2b2c0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
2b2d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e  .**.** The seven
2b2e0 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e  th, eighth and n
2b2f0 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  inth parameters,
2b300 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
2b310 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
2b320 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
2b330 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
2b340 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2b350 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2b360 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2b370 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20  e. A scalar SQL 
2b380 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2b390 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
2b3a0 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
2b3b0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
2b3c0 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y, NULL pointers
2b3d0 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
2b3e0 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
2b3f0 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
2b400 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72  ameters. An aggr
2b410 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2b420 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2b430 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2b440 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
2b450 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68  inal and NULL sh
2b460 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66  ould be passed f
2b470 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c  or xFunc. To del
2b480 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
2b490 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
2b4a0 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
2b4b0 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20  ss NULL for all 
2b4c0 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 63  three function c
2b4d0 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
2b4e0 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
2b4f0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
2b500 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2b510 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2b520 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
2b530 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
2b540 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
2b550 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
2b560 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
2b570 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
2b580 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
2b590 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 74  ncodings.  SQLit
2b5a0 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
2b5b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2b5c0 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
2b5d0 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
2b5e0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
2b5f0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
2b600 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
2b610 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ANTS:.**.** {H16
2b620 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  103} The [sqlite
2b630 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b640 6e 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  n16()] interface
2b650 20 62 65 68 61 76 65 73 20 65 78 61 63 74 6c 79   behaves exactly
2b660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 69 6b  .**          lik
2b670 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2b680 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 69 6e  e_function()] in
2b690 20 65 76 65 72 79 20 77 61 79 20 65 78 63 65 70   every way excep
2b6a0 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20 20 20  t that it.**    
2b6b0 20 20 20 20 20 20 69 6e 74 65 72 70 72 65 74 73        interprets
2b6c0 20 74 68 65 20 7a 46 75 6e 63 74 69 6f 6e 4e 61   the zFunctionNa
2b6d0 6d 65 20 61 72 67 75 6d 65 6e 74 20 61 73 20 7a  me argument as z
2b6e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2b6f0 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20  TF-16.**        
2b700 20 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72    native byte or
2b710 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  der instead of a
2b720 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2b730 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b  d UTF-8..**.** {
2b740 48 31 36 31 30 36 7d 20 41 20 73 75 63 63 65 73  H16106} A succes
2b750 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
2b760 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
2b770 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2b780 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2b790 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  N,E,...)] interf
2b7a0 61 63 65 20 72 65 67 69 73 74 65 72 73 0a 2a 2a  ace registers.**
2b7b0 20 20 20 20 20 20 20 20 20 20 6f 72 20 72 65 70            or rep
2b7c0 6c 61 63 65 73 20 63 61 6c 6c 62 61 63 6b 20 66  laces callback f
2b7d0 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20  unctions in the 
2b7e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2b7f0 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20  tion] D.**      
2b800 20 20 20 20 75 73 65 64 20 74 6f 20 69 6d 70 6c      used to impl
2b810 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
2b820 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77  nction named X w
2b830 69 74 68 20 4e 20 70 61 72 61 6d 65 74 65 72 73  ith N parameters
2b840 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
2b850 20 68 61 76 69 6e 67 20 61 20 70 72 65 66 65 72   having a prefer
2b860 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
2b870 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48  g of E..**.** {H
2b880 31 36 31 30 39 7d 20 41 20 73 75 63 63 65 73 73  16109} A success
2b890 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
2b8a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b8b0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
2b8c0 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,S,L)].**       
2b8d0 20 20 20 72 65 70 6c 61 63 65 73 20 74 68 65 20     replaces the 
2b8e0 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76  P, F, S, and L v
2b8f0 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79 20 70  alues from any p
2b900 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 0a  rior calls with.
2b910 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2b920 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e  same D, X, N, an
2b930 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a  d E values..**.*
2b940 2a 20 7b 48 31 36 31 31 32 7d 20 54 68 65 20 5b  * {H16112} The [
2b950 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2b960 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29  unction(D,X,...)
2b970 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  ] interface fail
2b980 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  s with.**       
2b990 20 20 20 61 20 72 65 74 75 72 6e 20 63 6f 64 65     a return code
2b9a0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   of [SQLITE_ERRO
2b9b0 52 5d 20 69 66 20 74 68 65 20 53 51 4c 20 66 75  R] if the SQL fu
2b9c0 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73  nction name X is
2b9d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 6e  .**          lon
2b9e0 67 65 72 20 74 68 61 6e 20 32 35 35 20 62 79 74  ger than 255 byt
2b9f0 65 73 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  es exclusive of 
2ba00 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
2ba10 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  tor..**.** {H161
2ba20 31 38 7d 20 45 69 74 68 65 72 20 46 20 6d 75 73  18} Either F mus
2ba30 74 20 62 65 20 4e 55 4c 4c 20 61 6e 64 20 53 20  t be NULL and S 
2ba40 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55  and L are non-NU
2ba50 4c 4c 20 6f 72 20 65 6c 73 65 20 46 0a 2a 2a 20  LL or else F.** 
2ba60 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d           is non-
2ba70 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c  NULL and S and L
2ba80 20 61 72 65 20 4e 55 4c 4c 2c 20 6f 74 68 65 72   are NULL, other
2ba90 77 69 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  wise.**         
2baa0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2bab0 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2bac0 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 72 65 74 75  E,P,F,S,L)] retu
2bad0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  rns [SQLITE_ERRO
2bae0 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32  R]..**.** {H1612
2baf0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
2bb00 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2bb10 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  D,...)] interfac
2bb20 65 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a  e fails with an.
2bb30 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f  **          erro
2bb40 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
2bb50 45 5f 42 55 53 59 5d 20 69 66 20 74 68 65 72 65  E_BUSY] if there
2bb60 20 65 78 69 73 74 20 5b 70 72 65 70 61 72 65 64   exist [prepared
2bb70 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20   statements].** 
2bb80 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61           associa
2bb90 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
2bba0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2bbb0 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  n] D..**.** {H16
2bbc0 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  124} The [sqlite
2bbd0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2bbe0 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e  n(D,X,N,...)] in
2bbf0 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
2bc00 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  th an.**        
2bc10 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20    error code of 
2bc20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
2bc30 66 20 70 61 72 61 6d 65 74 65 72 20 4e 20 28 73  f parameter N (s
2bc40 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 6e 75  pecifying the nu
2bc50 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  mber.**         
2bc60 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   of arguments to
2bc70 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2bc80 6e 20 62 65 69 6e 67 20 72 65 67 69 73 74 65 72  n being register
2bc90 65 64 29 20 69 73 20 6c 65 73 73 0a 2a 2a 20 20  ed) is less.**  
2bca0 20 20 20 20 20 20 20 20 74 68 61 6e 20 2d 31 20          than -1 
2bcb0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
2bcc0 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  127..**.** {H161
2bcd0 32 37 7d 20 57 68 65 6e 20 4e 20 69 73 20 6e 6f  27} When N is no
2bce0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  n-negative, the 
2bcf0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2bd00 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e  function(D,X,N,.
2bd10 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
2bd20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
2bd30 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62  s callbacks to b
2bd40 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  e invoked for th
2bd50 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a  e SQL function.*
2bd60 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64  *          named
2bd70 20 58 20 77 68 65 6e 20 74 68 65 20 6e 75 6d 62   X when the numb
2bd80 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2bd90 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
2bda0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ion is.**       
2bdb0 20 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a     exactly N..**
2bdc0 0a 2a 2a 20 7b 48 31 36 31 33 30 7d 20 57 68 65  .** {H16130} Whe
2bdd0 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68 65 20 5b  n N is -1, the [
2bde0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2bdf0 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e  unction(D,X,N,..
2be00 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
2be10 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
2be20 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65   callbacks to be
2be30 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65   invoked for the
2be40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL function.**
2be50 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20            named 
2be60 58 20 77 69 74 68 20 61 6e 79 20 6e 75 6d 62 65  X with any numbe
2be70 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a  r of arguments..
2be80 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 33 7d 20 57  **.** {H16133} W
2be90 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  hen calls to [sq
2bea0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2beb0 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29  ction(D,X,N,...)
2bec0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70  ].**          sp
2bed0 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69  ecify multiple i
2bee0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2bef0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2bf00 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20  ion X.**        
2bf10 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69    and when one i
2bf20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61  mplementation ha
2bf30 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f  s N>=0 and the o
2bf40 74 68 65 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a  ther has N=(-1).
2bf50 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2bf60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2bf70 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e  ith a non-zero N
2bf80 20 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a   is preferred..*
2bf90 2a 0a 2a 2a 20 7b 48 31 36 31 33 36 7d 20 57 68  *.** {H16136} Wh
2bfa0 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  en calls to [sql
2bfb0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2bfc0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e  tion(D,X,N,E,...
2bfd0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  )].**          s
2bfe0 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20  pecify multiple 
2bff0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2c000 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2c010 74 69 6f 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20  tion X with.**  
2c020 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
2c030 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2c040 65 6e 74 73 20 4e 20 62 75 74 20 77 69 74 68 20  ents N but with 
2c050 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20  different.**    
2c060 20 20 20 20 20 20 65 6e 63 6f 64 69 6e 67 73 20        encodings 
2c070 45 2c 20 74 68 65 6e 20 74 68 65 20 69 6d 70 6c  E, then the impl
2c080 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 72 65  ementation where
2c090 20 45 20 6d 61 74 63 68 65 73 20 74 68 65 0a 2a   E matches the.*
2c0a0 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
2c0b0 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
2c0c0 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a  preferred..**.**
2c0d0 20 7b 48 31 36 31 33 39 7d 20 46 6f 72 20 61 6e   {H16139} For an
2c0e0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2c0f0 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 65 64 20  unction created 
2c100 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
2c110 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
2c120 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2c130 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74 68 65  ,E,P,0,S,L)] the
2c140 20 66 69 6e 61 6c 69 7a 65 72 0a 2a 2a 20 20 20   finalizer.**   
2c150 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
2c160 4c 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 62 65  L will always be
2c170 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79   invoked exactly
2c180 20 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a 2a 20   once if the.** 
2c190 20 20 20 20 20 20 20 20 20 73 74 65 70 20 66 75           step fu
2c1a0 6e 63 74 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c  nction S is call
2c1b0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
2c1c0 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  imes..**.** {H16
2c1d0 31 34 32 7d 20 57 68 65 6e 20 53 51 4c 69 74 65  142} When SQLite
2c1e0 20 69 6e 76 6f 6b 65 73 20 65 69 74 68 65 72 20   invokes either 
2c1f0 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 53 74  the xFunc or xSt
2c200 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a  ep function of.*
2c210 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 61 70  *          an ap
2c220 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2c230 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  d SQL function o
2c240 72 20 61 67 67 72 65 67 61 74 65 20 63 72 65 61  r aggregate crea
2c250 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
2c260 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  by [sqlite3_crea
2c270 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f  te_function()] o
2c280 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
2c290 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c  e_function16()],
2c2a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2c2b0 6e 20 74 68 65 20 61 72 72 61 79 20 6f 66 20 5b  n the array of [
2c2c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c2d0 62 6a 65 63 74 73 20 70 61 73 73 65 64 20 61 73  bjects passed as
2c2e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c2f0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2c300 20 61 72 65 20 61 6c 77 61 79 73 20 5b 70 72 6f   are always [pro
2c310 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c320 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2c330 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
2c340 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
2c350 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2c360 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
2c370 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2c380 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2c390 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2c3a0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2c3b0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2c3c0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2c3d0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2c3e0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2c3f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2c400 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2c410 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2c420 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2c430 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
2c440 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c450 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
2c460 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
2c470 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
2c480 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2c490 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2c4a0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2c4b0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2c4c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2c4d0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2c4e0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2c4f0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2c500 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2c510 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2c520 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2c530 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2c540 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c550 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
2c560 73 20 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 32  s {H10267} <S502
2c570 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a  00> <H16100>.**.
2c580 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2c590 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
2c5a0 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
2c5b0 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
2c5c0 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
2c5d0 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
2c5e0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
2c5f0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
2c600 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
2c610 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2c620 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
2c630 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2c640 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
2c650 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2c660 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
2c670 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
2c680 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
2c690 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
2c6a0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
2c6b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2c6c0 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
2c6d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c6e0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
2c6f0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2c700 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
2c710 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
2c720 41 50 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74  API3REF: Obsolet
2c730 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  e Functions.**.*
2c740 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2c750 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62  s are all now ob
2c760 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65  solete.  In orde
2c770 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
2c780 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
2c790 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
2c7a0 64 65 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e  der code, we con
2c7b0 74 69 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74  tinue to support
2c7c0 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69  .** these functi
2c7d0 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ons.  However, n
2c7e0 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70  ew development p
2c7f0 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61  rojects should a
2c800 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
2c810 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2c820 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
2c830 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
2c840 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
2c850 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
2c860 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
2c870 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61  g to tell you wa
2c880 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69  nt they do..*/.i
2c890 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
2c8a0 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
2c8b0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e  e3_context*);.in
2c8c0 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
2c8d0 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
2c8e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  ;.int sqlite3_tr
2c8f0 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
2c900 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
2c910 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69  qlite3_stmt*);.i
2c920 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
2c930 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
2c940 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68  .void sqlite3_th
2c950 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
2c960 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
2c970 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
2c980 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2c990 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
2c9a0 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2c9b0 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
2c9c0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
2c9d0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
2c9e0 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48 31  meter Values {H1
2c9f0 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  5100} <S20200>.*
2ca00 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
2ca10 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
2ca20 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
2ca30 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2ca40 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
2ca50 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
2ca60 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
2ca70 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
2ca80 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
2ca90 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
2caa0 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ggregate..**.** 
2cab0 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
2cac0 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
2cad0 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
2cae0 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
2caf0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
2cb00 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2cb10 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
2cb20 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2cb30 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
2cb40 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
2cb50 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2cb60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
2cb70 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
2cb80 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65  * The 4th parame
2cb90 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
2cba0 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
2cbb0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
2cbc0 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
2cbd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2cbe0 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
2cbf0 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
2cc00 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
2cc10 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
2cc20 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
2cc30 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
2cc40 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
2cc50 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
2cc60 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
2cc70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2cc80 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
2cc90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
2cca0 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
2ccb0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2ccc0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2ccd0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
2cce0 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
2ccf0 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
2cd00 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2cd10 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
2cd20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
2cd30 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
2cd40 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2cd50 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
2cd60 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
2cd70 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
2cd80 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
2cd90 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
2cda0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
2cdb0 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
2cdc0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2cdd0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
2cde0 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
2cdf0 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
2ce00 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
2ce10 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
2ce20 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
2ce30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
2ce40 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
2ce50 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
2ce60 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
2ce70 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
2ce80 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
2ce90 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
2cea0 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
2ceb0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
2cec0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
2ced0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
2cee0 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
2cef0 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
2cf00 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
2cf10 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
2cf20 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
2cf30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2cf40 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2cf50 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
2cf60 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
2cf70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
2cf80 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
2cf90 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
2cfa0 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
2cfb0 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
2cfc0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2cfd0 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
2cfe0 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
2cff0 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
2d000 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
2d010 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
2d020 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
2d030 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
2d040 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
2d050 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
2d060 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
2d070 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
2d080 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
2d090 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
2d0a0 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
2d0b0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
2d0c0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
2d0d0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
2d0e0 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
2d0f0 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
2d100 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ..**.** Please p
2d110 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
2d120 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
2d130 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
2d140 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
2d150 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
2d160 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
2d170 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d180 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
2d190 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2d1a0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
2d1b0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
2d1c0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
2d1d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2d1e0 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
2d1f0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2d200 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
2d210 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2d220 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2d230 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
2d240 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2d250 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
2d260 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2d270 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
2d280 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
2d290 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
2d2a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
2d2b0 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a  ] parameters..**
2d2c0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2d2d0 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 33 7d 20 54  **.** {H15103} T
2d2e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2d2f0 65 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72  e_blob(V)] inter
2d300 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2d310 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2d320 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d330 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2d340 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64   into a BLOB and
2d350 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
2d360 20 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e    returns a poin
2d370 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65  ter to the conve
2d380 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  rted value..**.*
2d390 2a 20 7b 48 31 35 31 30 36 7d 20 54 68 65 20 5b  * {H15106} The [
2d3a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2d3b0 74 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61 63  tes(V)] interfac
2d3c0 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2d3d0 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
2d3e0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2d3f0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
2d400 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
2d410 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
2d420 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
2d430 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
2d440 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
2d450 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
2d460 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
2d470 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76  ll to [sqlite3_v
2d480 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72  alue_blob(V)] or
2d490 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2d4a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2d4b0 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  (V)]..**.** {H15
2d4c0 31 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  109} The [sqlite
2d4d0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2d4e0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  V)] interface re
2d4f0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
2d500 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
2d510 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2d520 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
2d530 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2d540 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
2d550 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
2d560 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2d570 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
2d580 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
2d590 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2d5a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2d5b0 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  V)],.**         
2d5c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d5d0 74 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f 72  text16be(V)], or
2d5e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d5f0 74 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a  text16le(V)]..**
2d600 0a 2a 2a 20 7b 48 31 35 31 31 32 7d 20 54 68 65  .** {H15112} The
2d610 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d620 64 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65 72  double(V)] inter
2d630 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2d640 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2d650 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d660 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2d670 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67   into a floating
2d680 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64   point value and
2d690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2d6a0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
2d6b0 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  hat value..**.**
2d6c0 20 7b 48 31 35 31 31 35 7d 20 54 68 65 20 5b 73   {H15115} The [s
2d6d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2d6e0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2d6f0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2d700 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2d710 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d720 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2d730 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
2d740 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
2d750 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
2d760 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74  the lower 32 bit
2d770 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65  s of that intege
2d780 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 38  r..**.** {H15118
2d790 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2d7a0 61 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d 20 69  alue_int64(V)] i
2d7b0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2d7c0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2d7d0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2d7e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2d7f0 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62  ct V into a 64-b
2d800 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2d810 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  r and.**        
2d820 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
2d830 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
2d840 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 31 7d  ..**.** {H15121}
2d850 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2d860 6c 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e 74  lue_text(V)] int
2d870 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2d880 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2d890 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2d8a0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2d8b0 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
2d8c0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
2d8d0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
2d8e0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
2d8f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
2d900 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
2d910 48 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71 6c  H15124} The [sql
2d920 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2d930 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  6(V)] interface 
2d940 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2d950 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2d960 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2d970 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2d980 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2d990 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20  ed 2-byte.**    
2d9a0 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54        aligned UT
2d9b0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
2d9c0 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
2d9d0 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
2d9e0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2d9f0 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
2da00 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 37 7d 20 54  **.** {H15127} T
2da10 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2da20 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20 69  e_text16be(V)] i
2da30 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2da40 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2da50 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2da60 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2da70 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
2da80 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
2da90 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
2daa0 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 62 69  ligned UTF-16 bi
2dab0 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20  g-endian.**     
2dac0 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
2dad0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2dae0 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
2daf0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 30 7d  ..**.** {H15130}
2db00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2db10 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d  lue_text16le(V)]
2db20 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2db30 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2db40 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2db50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2db60 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
2db70 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d  ro-terminated 2-
2db80 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  byte.**         
2db90 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20   aligned UTF-16 
2dba0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a  little-endian.**
2dbb0 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
2dbc0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2dbd0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
2dbe0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
2dbf0 35 31 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  5133} The [sqlit
2dc00 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56 29  e3_value_type(V)
2dc10 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2dc20 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
2dc30 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
2dc40 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e  ULL], [SQLITE_IN
2dc50 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
2dc60 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20  FLOAT],.**      
2dc70 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54      [SQLITE_TEXT
2dc80 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c  ], or [SQLITE_BL
2dc90 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
2dca0 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  te for.**       
2dcb0 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
2dcc0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e  value] object V.
2dcd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 36 7d 20  .**.** {H15136} 
2dce0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2dcf0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
2dd00 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2dd10 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20 20 20 20  nverts.**       
2dd20 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65     the [protecte
2dd30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2dd40 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 65   object V into e
2dd50 69 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65 72  ither an integer
2dd60 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2dd70 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
2dd80 20 76 61 6c 75 65 20 69 66 20 69 74 20 63 61 6e   value if it can
2dd90 20 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20 6c   do so without l
2dda0 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  oss of.**       
2ddb0 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20     information, 
2ddc0 61 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 20  and returns one 
2ddd0 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  of [SQLITE_NULL]
2dde0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  ,.**          [S
2ddf0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20  QLITE_INTEGER], 
2de00 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
2de10 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f  [SQLITE_TEXT], o
2de20 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
2de30 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61  QLITE_BLOB] as a
2de40 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74  ppropriate for t
2de50 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2de60 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2de70 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2de80 56 20 61 66 74 65 72 20 74 68 65 20 63 6f 6e 76  V after the conv
2de90 65 72 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a  ersion attempt..
2dea0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
2deb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
2dec0 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
2ded0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2dee0 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
2def0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2df00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2df10 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
2df20 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
2df30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
2df40 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
2df50 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2df60 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
2df70 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
2df80 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2df90 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
2dfa0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
2dfb0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
2dfc0 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
2dfd0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
2dfe0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
2dff0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2e000 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2e010 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
2e020 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2e030 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
2e040 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2e050 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2e060 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
2e070 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2e080 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2e090 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
2e0a0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2e0b0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
2e0c0 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
2e0d0 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
2e0e0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
2e0f0 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
2e100 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 36  ion Context {H16
2e110 32 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  210} <S20200>.**
2e120 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
2e130 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67  tation of aggreg
2e140 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2e150 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  s use this routi
2e160 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a  ne to allocate.*
2e170 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f  * a structure fo
2e180 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
2e190 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  state..**.** The
2e1a0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
2e1b0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2e1c0 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74  e_context() rout
2e1d0 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66 6f  ine is called fo
2e1e0 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61  r a.** particula
2e1f0 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c  r aggregate, SQL
2e200 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42  ite allocates nB
2e210 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  ytes of memory, 
2e220 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 0a  zeroes out that.
2e230 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  ** memory, and r
2e240 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2e250 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e   to it. On secon
2e260 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
2e270 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
2e280 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2e290 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65  ontext() for the
2e2a0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
2e2b0 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a  function index,.
2e2c0 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
2e2d0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
2e2e0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
2e2f0 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  on of the aggreg
2e300 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74  ate can use.** t
2e310 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66  he returned buff
2e320 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65  er to accumulate
2e330 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   data..**.** SQL
2e340 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
2e350 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f  y frees the allo
2e360 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65  cated buffer whe
2e370 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  n the aggregate.
2e380 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  ** query conclud
2e390 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
2e3a0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68  rst parameter sh
2e3b0 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f  ould be a copy o
2e3c0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
2e3d0 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
2e3e0 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
2e3f0 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
2e400 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
2e410 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2e420 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
2e430 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
2e440 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e  regate function.
2e450 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2e460 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2e470 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2e480 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2e490 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
2e4a0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2e4b0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
2e4c0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2e4d0 2a 2a 20 7b 48 31 36 32 31 31 7d 20 54 68 65 20  ** {H16211} The 
2e4e0 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e  first invocation
2e4f0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67 67   of [sqlite3_agg
2e500 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2e510 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20  ,N)] for.**     
2e520 20 20 20 20 20 61 20 70 61 72 74 69 63 75 6c 61       a particula
2e530 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 6e  r instance of an
2e540 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2e550 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74 69  ion (for a parti
2e560 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20 20  cular.**        
2e570 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61 75    context C) cau
2e580 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61 6c  ses SQLite to al
2e590 6c 6f 63 61 74 65 20 4e 20 62 79 74 65 73 20 6f  locate N bytes o
2e5a0 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20  f memory,.**    
2e5b0 20 20 20 20 20 20 7a 65 72 6f 20 74 68 61 74 20        zero that 
2e5c0 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
2e5d0 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  rn a pointer to 
2e5e0 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65  the allocated me
2e5f0 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  mory..**.** {H16
2e600 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79  213} If a memory
2e610 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2e620 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 0a  r occurs during.
2e630 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2e640 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2e650 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74 68 65  ontext(C,N)] the
2e660 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72  n the function r
2e670 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20  eturns 0..**.** 
2e680 7b 48 31 36 32 31 35 7d 20 53 65 63 6f 6e 64 20  {H16215} Second 
2e690 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 69  and subsequent i
2e6a0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a  nvocations of.**
2e6b0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2e6c0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2e6d0 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20 74  text(C,N)] for t
2e6e0 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78 74 20  he same context 
2e6f0 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20 20  pointer C.**    
2e700 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74 68 65        ignore the
2e710 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64   N parameter and
2e720 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65   return a pointe
2e730 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a 2a  r to the same.**
2e740 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63 6b 20            block 
2e750 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  of memory return
2e760 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2e770 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
2e780 2a 20 7b 48 31 36 32 31 37 7d 20 54 68 65 20 6d  * {H16217} The m
2e790 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
2e7a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  by [sqlite3_aggr
2e7b0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2e7c0 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  N)] is.**       
2e7d0 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79     automatically
2e7e0 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20 6e 65   freed on the ne
2e7f0 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  xt call to [sqli
2e800 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
2e810 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
2e820 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2e830 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2e840 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 63 6f  ed statement] co
2e850 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20  ntaining.**     
2e860 20 20 20 20 20 74 68 65 20 61 67 67 72 65 67 61       the aggrega
2e870 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f  te function asso
2e880 63 69 61 74 65 64 20 77 69 74 68 20 63 6f 6e 74  ciated with cont
2e890 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  ext C..*/.void *
2e8a0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2e8b0 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
2e8c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2e8d0 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
2e8e0 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
2e8f0 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
2e900 73 20 7b 48 31 36 32 34 30 7d 20 3c 53 32 30 32  s {H16240} <S202
2e910 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2e920 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2e930 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2e940 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2e950 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
2e960 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
2e970 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
2e980 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2e990 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2e9a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2e9b0 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2e9c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2e9d0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
2e9e0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
2e9f0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
2ea00 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
2ea10 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2ea20 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  tion. {END}.**.*
2ea30 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
2ea40 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2ea50 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2ea60 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
2ea70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2ea80 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2ea90 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
2eaa0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2eab0 0a 2a 2a 20 7b 48 31 36 32 34 33 7d 20 54 68 65  .** {H16243} The
2eac0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2ead0 61 74 61 28 43 29 5d 20 69 6e 74 65 72 66 61 63  ata(C)] interfac
2eae0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
2eaf0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2eb00 20 20 20 20 50 20 70 6f 69 6e 74 65 72 20 66 72      P pointer fr
2eb10 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
2eb20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2eb30 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2eb40 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
2eb50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2eb60 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c  _function16(D,X,
2eb70 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61  N,E,P,F,S,L)] ca
2eb80 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  ll that.**      
2eb90 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74      registered t
2eba0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2ebb0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2ebc0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2ebd0 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ] C..*/.void *sq
2ebe0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2ebf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2ec00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ec10 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2ec20 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
2ec30 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c  tions {H16250} <
2ec40 53 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a  S60600><S20200>.
2ec50 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2ec60 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2ec70 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
2ec80 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2ec90 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
2eca0 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
2ecb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
2ecc0 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
2ecd0 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2ece0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ecf0 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2ed00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2ed10 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
2ed20 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
2ed30 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
2ed40 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
2ed50 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2ed60 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  tion..**.** INVA
2ed70 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
2ed80 31 36 32 35 33 7d 20 54 68 65 20 5b 73 71 6c 69  16253} The [sqli
2ed90 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2eda0 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65 72 66  andle(C)] interf
2edb0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
2edc0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  py of the.**    
2edd0 20 20 20 20 20 20 44 20 70 6f 69 6e 74 65 72 20        D pointer 
2ede0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
2edf0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2ee00 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  n(D,X,N,E,P,F,S,
2ee10 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  L)].**          
2ee20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  or [sqlite3_crea
2ee30 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c  te_function16(D,
2ee40 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20  X,N,E,P,F,S,L)] 
2ee50 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20  call that.**    
2ee60 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
2ee70 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2ee80 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  n associated wit
2ee90 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  h [sqlite3_conte
2eea0 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65  xt] C..*/.sqlite
2eeb0 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
2eec0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
2eed0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2eee0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2eef0 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
2ef00 61 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 30  ary Data {H16270
2ef10 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20200>.**.**
2ef20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
2ef30 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
2ef40 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
2ef50 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
2ef60 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
2ef70 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
2ef80 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
2ef90 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
2efa0 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
2efb0 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
2efc0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2efd0 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
2efe0 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
2eff0 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
2f000 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
2f010 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
2f020 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
2f030 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68  be preserved. Th
2f040 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65  is may.** be use
2f050 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
2f060 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72  to add a regular
2f070 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
2f080 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66  hing scalar.** f
2f090 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
2f0a0 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
2f0b0 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
2f0c0 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65  ression is store
2f0d0 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
2f0e0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2f0f0 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
2f100 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
2f110 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
2f120 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
2f130 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
2f140 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
2f150 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
2f160 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
2f170 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2f180 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
2f190 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
2f1a0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
2f1b0 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
2f1c0 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
2f1d0 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
2f1e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
2f1f0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2f200 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
2f210 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2f220 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
2f230 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
2f240 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
2f250 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
2f260 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
2f270 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
2f280 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
2f290 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2f2a0 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d  unction. If no m
2f2b0 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
2f2c0 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65   ever.** been se
2f2d0 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72  t for the Nth ar
2f2e0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75  gument of the fu
2f2f0 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68  nction, or if th
2f300 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
2f310 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ** function para
2f320 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65  meter has change
2f330 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61  d since the meta
2f340 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a  -data was set,.*
2f350 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67  * then sqlite3_g
2f360 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74  et_auxdata() ret
2f370 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
2f380 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
2f390 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2f3a0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ta() interface s
2f3b0 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74  aves the metadat
2f3c0 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  a.** pointed to 
2f3d0 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  by its 3rd param
2f3e0 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61  eter as the meta
2f3f0 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
2f400 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
2f410 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2f420 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2f430 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a  n.  Subsequent.*
2f440 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
2f450 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2f460 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68   might return th
2f470 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68  is data, if it h
2f480 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64  as.** not been d
2f490 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20  estroyed..** If 
2f4a0 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  it is not NULL, 
2f4b0 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
2f4c0 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
2f4d0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69  r.** function gi
2f4e0 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70  ven by the 4th p
2f4f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2f500 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2f510 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61  ) on.** the meta
2f520 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f  data when the co
2f530 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
2f540 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
2f550 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65  hanges.** or whe
2f560 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
2f570 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77  ent completes, w
2f580 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
2f590 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  irst..**.** SQLi
2f5a0 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61  te is free to ca
2f5b0 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ll the destructo
2f5c0 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64  r and drop metad
2f5d0 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61  ata on any.** pa
2f5e0 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66  rameter of any f
2f5f0 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74  unction at any t
2f600 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67  ime.  The only g
2f610 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74  uarantee is that
2f620 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74  .** the destruct
2f630 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  or will be calle
2f640 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74  d before the met
2f650 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64  adata is dropped
2f660 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74  ..**.** In pract
2f670 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
2f680 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
2f690 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
2f6a0 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73  s for.** express
2f6b0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f  ions that are co
2f6c0 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c  nstant at compil
2f6d0 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63  e time. This inc
2f6e0 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a  ludes literal.**
2f6f0 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20   values and SQL 
2f700 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a  variables..**.**
2f710 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2f720 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2f730 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2f740 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2f750 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2f760 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
2f770 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2f780 2a 0a 2a 2a 20 7b 48 31 36 32 37 32 7d 20 54 68  *.** {H16272} Th
2f790 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  e [sqlite3_get_a
2f7a0 75 78 64 61 74 61 28 43 2c 4e 29 5d 20 69 6e 74  uxdata(C,N)] int
2f7b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2f7c0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20   pointer.**     
2f7d0 20 20 20 20 20 74 6f 20 6d 65 74 61 64 61 74 61       to metadata
2f7e0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2f7f0 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74   the Nth paramet
2f800 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  er of the SQL fu
2f810 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
2f820 20 20 20 77 68 6f 73 65 20 63 6f 6e 74 65 78 74     whose context
2f830 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 69   is C, or NULL i
2f840 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  f there is no me
2f850 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
2f860 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  d.**          wi
2f870 74 68 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  th that paramete
2f880 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 34  r..**.** {H16274
2f890 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
2f8a0 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
2f8b0 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  ,D)] interface a
2f8c0 73 73 69 67 6e 73 20 61 20 6d 65 74 61 64 61 74  ssigns a metadat
2f8d0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  a.**          po
2f8e0 69 6e 74 65 72 20 50 20 74 6f 20 74 68 65 20 4e  inter P to the N
2f8f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
2f900 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2f910 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e   with context C.
2f920 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 36 7d 20  .**.** {H16276} 
2f930 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
2f940 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
2f950 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c  r D with a singl
2f960 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20  e argument.**   
2f970 20 20 20 20 20 20 20 77 68 69 63 68 20 69 73 20         which is 
2f980 74 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69  the metadata poi
2f990 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67  nter P following
2f9a0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20   a call to.**   
2f9b0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2f9c0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
2f9d0 50 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74  P,D)] when SQLit
2f9e0 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64  e ceases to hold
2f9f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2fa00 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a   metadata..**.**
2fa10 20 7b 48 31 36 32 37 37 7d 20 53 51 4c 69 74 65   {H16277} SQLite
2fa20 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20   ceases to hold 
2fa30 6d 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20  metadata for an 
2fa40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  SQL function par
2fa50 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ameter.**       
2fa60 20 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75     when the valu
2fa70 65 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65  e of that parame
2fa80 74 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  ter changes..**.
2fa90 2a 2a 20 7b 48 31 36 32 37 38 7d 20 57 68 65 6e  ** {H16278} When
2faa0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
2fab0 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20  xdata(C,N,P,D)] 
2fac0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
2fad0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20  destructor.**   
2fae0 20 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64         is called
2faf0 20 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d   for any prior m
2fb00 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
2fb10 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
2fb20 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2fb30 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20        context C 
2fb40 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e  and parameter N.
2fb50 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 39 7d 20  .**.** {H16279} 
2fb60 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c  SQLite will call
2fb70 20 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72   destructors for
2fb80 20 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74   any metadata it
2fb90 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20   is holding.**  
2fba0 20 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 72          in a par
2fbb0 74 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65  ticular [prepare
2fbc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77  d statement] S w
2fbd0 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  hen either.**   
2fbe0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2fbf0 72 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71  reset(S)] or [sq
2fc00 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2fc10 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f  )] is called..*/
2fc20 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67  .void *sqlite3_g
2fc30 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
2fc40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2fc50 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65   N);.void sqlite
2fc60 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
2fc70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2fc80 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
2fc90 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
2fca0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fcb0 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
2fcc0 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
2fcd0 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
2fce0 20 7b 48 31 30 32 38 30 7d 20 3c 53 33 30 31 30   {H10280} <S3010
2fcf0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  0>.**.** These a
2fd00 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  re special value
2fd10 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75  s for the destru
2fd20 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73  ctor that is pas
2fd30 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
2fd40 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20   final argument 
2fd50 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
2fd60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2fd70 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68  _blob()].  If th
2fd80 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
2fd90 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49  argument is SQLI
2fda0 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65  TE_STATIC, it me
2fdb0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
2fdc0 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20  tent pointer is 
2fdd0 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20  constant.** and 
2fde0 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67  will never chang
2fdf0 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20  e.  It does not 
2fe00 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72  need to be destr
2fe10 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53 51  oyed.  The.** SQ
2fe20 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
2fe30 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
2fe40 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
2fe50 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
2fe60 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
2fe70 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
2fe80 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
2fe90 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
2fea0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2feb0 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
2fec0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
2fed0 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
2fee0 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
2fef0 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
2ff00 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
2ff10 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53  ++ compilers.  S
2ff20 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e  ee ticket #2191.
2ff30 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
2ff40 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
2ff50 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
2ff60 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
2ff70 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
2ff80 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
2ff90 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
2ffa0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
2ffb0 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
2ffc0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
2ffd0 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
2ffe0 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
2fff0 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
30000 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31 36  QL Function {H16
30010 34 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  400} <S20200>.**
30020 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
30030 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
30040 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
30050 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
30060 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
30070 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
30080 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
30090 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
300a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
300b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
300c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
300d0 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
300e0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
300f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
30100 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
30110 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
30120 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
30130 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
30140 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
30150 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
30160 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
30170 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
30180 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
30190 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
301a0 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
301b0 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
301c0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
301d0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  on..**.** The sq
301e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
301f0 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
30200 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
30210 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
30220 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30230 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
30240 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
30250 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
30260 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
30270 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
30280 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
30290 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
302a0 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
302b0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  rameter..**.** T
302c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
302d0 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74  t_zeroblob() int
302e0 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20  erfaces set the 
302f0 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
30300 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30310 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
30320 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61   be a BLOB conta
30330 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a  ining all zero.*
30340 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79  * bytes and N by
30350 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65  tes in size, whe
30360 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75  re N is the valu
30370 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72  e of the 2nd par
30380 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ameter..**.** Th
30390 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
303a0 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
303b0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
303c0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
303d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
303e0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
303f0 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
30400 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
30410 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
30420 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
30430 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
30440 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
30450 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30460 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
30470 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
30480 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
30490 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
304a0 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
304b0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
304c0 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
304d0 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
304e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
304f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30500 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
30510 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
30520 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
30530 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
30540 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69  ssage.  SQLite i
30550 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
30560 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
30570 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
30580 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
30590 29 20 61 73 20 55 54 46 2d 38 2e 20 53 51 4c 69  ) as UTF-8. SQLi
305a0 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
305b0 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
305c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
305d0 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
305e0 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
305f0 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49 66   byte order.  If
30600 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
30610 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
30620 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
30630 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
30640 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
30650 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53   negative then S
30660 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74  QLite takes as t
30670 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
30680 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20  age all text up 
30690 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
306a0 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
306b0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69 72  ..** If the thir
306c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
306d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
306e0 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
306f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30700 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
30710 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
30720 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
30730 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
30740 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
30750 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
30760 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
30770 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73  essage..** The s
30780 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30790 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
307a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
307b0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d  ().** routines m
307c0 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f  ake a private co
307d0 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  py of the error 
307e0 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66  message text bef
307f0 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75  ore.** they retu
30800 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  rn.  Hence, the 
30810 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
30820 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20   can deallocate 
30830 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65  or.** modify the
30840 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79   text after they
30850 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20   return without 
30860 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  harm..** The sql
30870 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30880 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
30890 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
308a0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
308b0 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
308c0 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
308d0 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
308e0 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 6c  tion.  By defaul
308f0 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
30900 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
30910 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71 75  RROR.  A subsequ
30920 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
30930 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30940 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
30950 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
30960 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72  ) resets the err
30970 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54  or code to SQLIT
30980 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54  E_ERROR..**.** T
30990 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
309a0 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  t_toobig() inter
309b0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
309c0 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  te to throw an e
309d0 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69  rror.** indicati
309e0 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
309f0 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c   or BLOB is to l
30a00 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
30a10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
30a20 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d  te3_result_nomem
30a30 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
30a40 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
30a50 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
30a60 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
30a70 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
30a80 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a  ion failed..**.*
30a90 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
30aa0 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72  sult_int() inter
30ab0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
30ac0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
30ad0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30ae0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
30af0 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62  n to be the 32-b
30b00 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
30b10 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
30b20 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
30b30 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ment..** The sql
30b40 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
30b50 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  4() interface se
30b60 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
30b70 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
30b80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30b90 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
30ba0 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e   the 64-bit sign
30bb0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
30bc0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
30bd0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
30be0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
30bf0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
30c00 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
30c10 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
30c20 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
30c30 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30c40 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
30c50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
30c60 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
30c70 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
30c80 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
30c90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
30ca0 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
30cb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
30cc0 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
30cd0 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
30ce0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
30cf0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
30d00 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
30d10 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
30d20 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
30d30 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
30d40 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
30d50 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
30d60 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
30d70 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
30d80 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
30d90 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53  spectively..** S
30da0 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20  QLite takes the 
30db0 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d  text result from
30dc0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30dd0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64   from.** the 2nd
30de0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
30df0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30e00 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
30e10 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  s..** If the 3rd
30e20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
30e30 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30e40 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
30e50 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
30e60 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
30e70 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
30e80 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
30e90 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
30ea0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
30eb0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
30ec0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
30ed0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
30ee0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
30ef0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
30f00 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
30f10 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
30f20 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
30f30 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
30f40 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
30f50 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
30f60 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
30f70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
30f80 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
30f90 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66  on result..** If
30fa0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
30fb0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
30fc0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
30fd0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
30fe0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
30ff0 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
31000 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
31010 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
31020 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
31030 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
31040 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  on the text or B
31050 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20  LOB result when 
31060 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
31070 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
31080 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20  sult..** If the 
31090 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
310a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
310b0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
310c0 61 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  aces or.** sqlit
310d0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
310e0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
310f0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
31100 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
31110 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
31120 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
31130 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
31140 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
31150 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
31160 6f 70 79 20 74 68 65 20 69 74 20 6f 72 20 63 61  opy the it or ca
31170 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
31180 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
31190 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
311a0 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68  result..** If th
311b0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
311c0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
311d0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
311e0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
311f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
31200 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
31210 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
31220 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
31230 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
31240 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
31250 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
31260 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
31270 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
31280 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
31290 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
312a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
312b0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
312c0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
312d0 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
312e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
312f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
31300 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a  be a copy the.**
31310 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
31320 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
31330 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
31340 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
31350 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  er.  The.** sqli
31360 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
31370 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
31380 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
31390 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
313a0 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20  .** so that the 
313b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
313c0 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
313d0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
313e0 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
313f0 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
31400 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31410 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
31420 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
31430 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71   A [protected sq
31440 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
31450 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
31460 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
31470 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
31480 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31490 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
314a0 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
314b0 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
314c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
314d0 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
314e0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
314f0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
31500 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
31510 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
31520 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
31530 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
31540 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
31550 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31560 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31570 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
31580 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
31590 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
315a0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
315b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
315c0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
315d0 2a 2a 20 7b 48 31 36 34 30 33 7d 20 54 68 65 20  ** {H16403} The 
315e0 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20 76  default return v
315f0 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53 51  alue from any SQ
31600 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55  L function is NU
31610 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30  LL..**.** {H1640
31620 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
31630 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c  result_blob(C,V,
31640 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,D)] interface 
31650 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
31660 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
31670 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
31680 20 43 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20   C to be a BLOB 
31690 74 68 61 74 20 69 73 20 4e 20 62 79 74 65 73 0a  that is N bytes.
316a0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 6c  **          in l
316b0 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68 20 63  ength and with c
316c0 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64 20 74  ontent pointed t
316d0 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48  o by V..**.** {H
316e0 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  16409} The [sqli
316f0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
31700 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63  e(C,V)] interfac
31710 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
31720 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
31730 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
31740 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 66  on C to be the f
31750 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
31760 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  lue V..**.** {H1
31770 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  6412} The [sqlit
31780 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
31790 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  C,V,N)] interfac
317a0 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65  e changes the re
317b0 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
317c0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
317d0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
317e0 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
317f0 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
31800 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
31810 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 38 20 65  R] and a UTF-8 e
31820 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f 70  rror message cop
31830 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f  ied from V up to
31840 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
31850 20 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74 65   first zero byte
31860 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65   or until N byte
31870 73 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20  s are read if N 
31880 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a  is positive..**.
31890 2a 2a 20 7b 48 31 36 34 31 35 7d 20 54 68 65 20  ** {H16415} The 
318a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
318b0 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20  error16(C,V,N)] 
318c0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
318d0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
318e0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
318f0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
31900 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
31910 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
31920 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
31930 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61  ITE_ERROR] and a
31940 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
31950 79 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72 20  yte order error 
31960 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20  message.**      
31970 20 20 20 20 63 6f 70 69 65 64 20 66 72 6f 6d 20      copied from 
31980 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
31990 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
319a0 72 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74  r or until N byt
319b0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  es.**          a
319c0 72 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20  re read if N is 
319d0 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  positive..**.** 
319e0 7b 48 31 36 34 31 38 7d 20 54 68 65 20 5b 73 71  {H16418} The [sq
319f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31a00 6f 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e  or_toobig(C)] in
31a10 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
31a20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
31a30 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
31a40 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74  the function C t
31a50 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
31a60 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
31a70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
31a80 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e  QLITE_TOOBIG] an
31a90 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  d an appropriate
31aa0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
31ab0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 31 7d 20 54  **.** {H16421} T
31ac0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
31ad0 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43  lt_error_nomem(C
31ae0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
31af0 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a  nges the return.
31b00 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
31b10 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
31b20 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
31b30 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
31b40 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
31b50 20 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d     [SQLITE_NOMEM
31b60 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72  ] and an appropr
31b70 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
31b80 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32  ge..**.** {H1642
31b90 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
31ba0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
31bb0 65 28 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 63  e(C,E)] interfac
31bc0 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65  e changes the re
31bd0 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
31be0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75   value of the fu
31bf0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
31c00 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
31c10 20 65 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a   error code E..*
31c20 2a 20 20 20 20 20 20 20 20 20 20 54 68 65 20 65  *          The e
31c30 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
31c40 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
31c50 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 37 7d 20 54  **.** {H16427} T
31c60 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
31c70 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74  lt_int(C,V)] int
31c80 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
31c90 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
31ca0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
31cb0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
31cc0 74 68 65 20 33 32 2d 62 69 74 20 69 6e 74 65 67  the 32-bit integ
31cd0 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a  er value V..**.*
31ce0 2a 20 7b 48 31 36 34 33 30 7d 20 54 68 65 20 5b  * {H16430} The [
31cf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
31d00 6e 74 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 72  nt64(C,V)] inter
31d10 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
31d20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
31d30 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
31d40 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
31d50 65 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  e 64-bit integer
31d60 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20   value V..**.** 
31d70 7b 48 31 36 34 33 33 7d 20 54 68 65 20 5b 73 71  {H16433} The [sq
31d80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
31d90 6c 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20  l(C)] interface 
31da0 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
31db0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
31dc0 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
31dd0 20 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a   C to be NULL..*
31de0 2a 0a 2a 2a 20 7b 48 31 36 34 33 36 7d 20 54 68  *.** {H16436} Th
31df0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
31e00 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
31e10 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
31e20 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
31e30 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
31e40 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
31e50 20 62 65 20 74 68 65 20 55 54 46 2d 38 20 73 74   be the UTF-8 st
31e60 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
31e70 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
31e80 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20  st zero if N is 
31e90 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
31ea0 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73       or the firs
31eb0 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69  t N bytes of V i
31ec0 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
31ed0 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ive..**.** {H164
31ee0 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  39} The [sqlite3
31ef0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43  _result_text16(C
31f00 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,V,N,D)] interfa
31f10 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
31f20 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
31f30 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
31f40 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
31f50 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
31f60 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20  te order.**     
31f70 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70       string V up
31f80 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
31f90 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  ro if N is negat
31fa0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
31fb0 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62  or the first N b
31fc0 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69  ytes of V if N i
31fd0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a  s non-negative..
31fe0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 32 7d 20 54  **.** {H16442} T
31ff0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
32000 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
32010 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,D)] interface 
32020 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
32030 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
32040 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
32050 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46   C to be the UTF
32060 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a  -16 big-endian.*
32070 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
32080 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69  g V up to the fi
32090 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73  rst zero if N is
320a0 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20   negative.**    
320b0 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72        or the fir
320c0 73 74 20 4e 20 62 79 74 65 73 20 6f 72 20 56 20  st N bytes or V 
320d0 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  if N is non-nega
320e0 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  tive..**.** {H16
320f0 34 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  445} The [sqlite
32100 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
32110 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65  e(C,V,N,D)] inte
32120 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
32130 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
32140 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
32150 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
32160 68 65 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  he UTF-16 little
32170 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20  -endian.**      
32180 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20      string V up 
32190 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
321a0 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  o if N is negati
321b0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ve.**          o
321c0 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
321d0 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73  tes of V if N is
321e0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
321f0 2a 0a 2a 2a 20 7b 48 31 36 34 34 38 7d 20 54 68  *.** {H16448} Th
32200 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
32210 74 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e  t_value(C,V)] in
32220 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
32230 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
32240 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
32250 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
32260 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
32270 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
32280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a  .**          obj
32290 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ect V..**.** {H1
322a0 36 34 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  6451} The [sqlit
322b0 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
322c0 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ob(C,N)] interfa
322d0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
322e0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
322f0 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
32300 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 4e  ion C to be an N
32310 2d 62 79 74 65 20 42 4c 4f 42 20 6f 66 20 61 6c  -byte BLOB of al
32320 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b  l zeros..**.** {
32330 48 31 36 34 35 34 7d 20 54 68 65 20 5b 73 71 6c  H16454} The [sql
32340 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32350 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  r()] and [sqlite
32360 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
32370 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
32380 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 20  interfaces make 
32390 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69 72 20  a copy of their 
323a0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
323b0 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a 20  rings before.** 
323c0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 69           returni
323d0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35  ng..**.** {H1645
323e0 37 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74  7} If the D dest
323f0 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72  ructor parameter
32400 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
32410 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44  ult_blob(C,V,N,D
32420 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
32430 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32440 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20  text(C,V,N,D)], 
32450 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32460 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d  text16(C,V,N,D)]
32470 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
32480 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32490 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16be(C,V,N,D)]
324a0 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
324b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
324c0 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c  _text16le(C,V,N,
324d0 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74  D)] is the const
324e0 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  ant [SQLITE_STAT
324f0 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  IC].**          
32500 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 75 63 74  then no destruct
32510 6f 72 20 69 73 20 65 76 65 72 20 63 61 6c 6c 65  or is ever calle
32520 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65 72  d on the pointer
32530 20 56 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a 2a   V and SQLite.**
32540 20 20 20 20 20 20 20 20 20 20 61 73 73 75 6d 65            assume
32550 73 20 74 68 61 74 20 56 20 69 73 20 69 6d 6d 75  s that V is immu
32560 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  table..**.** {H1
32570 36 34 36 30 7d 20 49 66 20 74 68 65 20 44 20 64  6460} If the D d
32580 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65  estructor parame
32590 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
325a0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c  result_blob(C,V,
325b0 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
325c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
325d0 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29  lt_text(C,V,N,D)
325e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ], [sqlite3_resu
325f0 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c  lt_text16(C,V,N,
32600 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
32610 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32620 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c  _text16be(C,V,N,
32630 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
32640 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
32650 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56  ult_text16le(C,V
32660 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f  ,N,D)] is the co
32670 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20 20  nstant.**       
32680 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53     [SQLITE_TRANS
32690 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65 20 69  IENT] then the i
326a0 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 73 20  nterfaces makes 
326b0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
326c0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 6e            conten
326d0 74 20 6f 66 20 56 20 61 6e 64 20 72 65 74 61 69  t of V and retai
326e0 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a  ns the copy..**.
326f0 2a 2a 20 7b 48 31 36 34 36 33 7d 20 49 66 20 74  ** {H16463} If t
32700 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
32710 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
32720 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
32730 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
32740 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
32750 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
32760 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
32770 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
32780 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
32790 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
327a0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
327b0 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
327c0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
327d0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
327e0 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
327f0 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68 65 72  some value other
32800 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20   than.**        
32810 20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20    the constants 
32820 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 20  [SQLITE_STATIC] 
32830 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  and [SQLITE_TRAN
32840 53 49 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a 20 20  SIENT] then.**  
32850 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 77          SQLite w
32860 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
32870 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68  estructor D with
32880 20 56 20 61 73 20 69 74 73 20 6f 6e 6c 79 20 61   V as its only a
32890 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20  rgument.**      
328a0 20 20 20 20 77 68 65 6e 20 69 74 20 68 61 73 20      when it has 
328b0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68  finished with th
328c0 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f  e V value..*/.vo
328d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
328e0 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
328f0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
32900 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
32910 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
32920 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32930 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
32940 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
32950 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32960 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
32970 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
32980 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
32990 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
329a0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
329b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
329c0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
329d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
329e0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
329f0 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
32a00 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
32a10 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
32a20 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
32a30 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
32a40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32a50 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
32a60 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
32a70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32a80 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
32a90 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
32aa0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32ab0 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
32ac0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
32ad0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
32ae0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32af0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
32b00 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
32b10 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32b20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32b30 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
32b40 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
32b50 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
32b60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
32b70 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32b80 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
32b90 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
32ba0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
32bb0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
32bc0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
32bd0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
32be0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
32bf0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
32c00 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
32c10 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
32c20 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
32c30 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
32c40 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
32c50 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
32c60 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
32c70 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
32c80 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
32c90 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
32ca0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
32cb0 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
32cc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
32cd0 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
32ce0 67 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31 36  g Sequences {H16
32cf0 36 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a  600} <S20300>.**
32d00 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
32d10 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
32d20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  add new collatio
32d30 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74  n sequences to t
32d40 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
32d50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
32d60 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
32d70 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
32d80 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** The name of t
32d90 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  he new collation
32da0 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65   sequence is spe
32db0 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d  cified as a UTF-
32dc0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
32dd0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
32de0 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
32df0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32e00 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
32e10 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
32e20 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ing for sqlite3_
32e30 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32e40 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73  16(). In all cas
32e50 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69  es.** the name i
32e60 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
32e70 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
32e80 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
32e90 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
32ea0 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nt may be one of
32eb0 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b   the constants [
32ec0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
32ed0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
32ee0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  ] or [SQLITE_UTF
32ef0 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16BE], indicatin
32f00 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d  g that the user-
32f10 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74  supplied.** rout
32f20 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62  ine expects to b
32f30 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72  e passed pointer
32f40 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63  s to strings enc
32f50 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
32f60 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
32f70 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le-endian, or UT
32f80 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c  F-16 big-endian,
32f90 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 54   respectively. T
32fa0 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75  he.** third argu
32fb0 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20  ment might also 
32fc0 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  be [SQLITE_UTF16
32fd0 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64  _ALIGNED] to ind
32fe0 69 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 68  icate that.** th
32ff0 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  e routine expect
33000 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36  s pointers to 16
33010 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65  -bit word aligne
33020 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20  d strings.** of 
33030 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
33040 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
33050 6f 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70  of the host comp
33060 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f  uter..**.** A po
33070 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65  inter to the use
33080 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  r supplied routi
33090 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  ne must be passe
330a0 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a  d as the fifth.*
330b0 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20  * argument.  If 
330c0 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73  it is NULL, this
330d0 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
330e0 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c  deleting the col
330f0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
33100 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69  ce (so that SQLi
33110 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69  te cannot call i
33120 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45  t anymore)..** E
33130 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70  ach time the app
33140 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65  lication supplie
33150 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  d function is in
33160 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73  voked, it is pas
33170 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69  sed.** as its fi
33180 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20  rst parameter a 
33190 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
331a0 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
331b0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a  fourth argument.
331c0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  ** to sqlite3_cr
331d0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
331e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
331f0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
33200 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61  ..**.** The rema
33210 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20  ining arguments 
33220 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
33230 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74  on-supplied rout
33240 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69  ine are two stri
33250 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70  ngs,.** each rep
33260 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c  resented by a (l
33270 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69  ength, data) pai
33280 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e  r and encoded in
33290 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a   the encoding.**
332a0 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64   that was passed
332b0 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72   as the third ar
332c0 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20  gument when the 
332d0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
332e0 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74  ce was.** regist
332f0 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68 65  ered. {END}  The
33300 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
33310 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72  ined collation r
33320 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a  outine should.**
33330 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65   return negative
33340 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69  , zero or positi
33350 76 65 20 69 66 20 74 68 65 20 66 69 72 73 74 20  ve if the first 
33360 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74  string is less t
33370 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f  han,.** equal to
33380 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  , or greater tha
33390 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72  n the second str
333a0 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e  ing. i.e. (STRIN
333b0 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a  G1 - STRING2)..*
333c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
333d0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
333e0 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
333f0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
33400 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
33410 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 74  except that it t
33420 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72  akes an extra ar
33430 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
33440 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  a destructor for
33450 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  .** the collatio
33460 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74  n.  The destruct
33470 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65  or is called whe
33480 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
33490 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20  is.** destroyed 
334a0 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20  and is passed a 
334b0 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72  copy of the four
334c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69  th parameter voi
334d0 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66  d* pointer.** of
334e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   the sqlite3_cre
334f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33500 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e  ()..** Collation
33510 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20  s are destroyed 
33520 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
33530 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
33540 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  r calls to the.*
33550 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  * collation crea
33560 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
33570 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61  r when the [data
33580 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33590 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73   is closed.** us
335a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
335b0 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  se()]..**.** INV
335c0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
335d0 48 31 36 36 30 33 7d 20 41 20 73 75 63 63 65 73  H16603} A succes
335e0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65  sful call to the
335f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
33600 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33610 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c  lation_v2(B,X,E,
33620 50 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  P,F,D)] interfac
33630 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
33640 67 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f 6e  gisters function
33650 20 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61 72   F as the compar
33660 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73  ison function us
33670 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ed to.**        
33680 20 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c    implement coll
33690 61 74 69 6f 6e 20 58 20 6f 6e 20 74 68 65 20 5b  ation X on the [
336a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
336b0 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 20  ion] B for.**   
336c0 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 73         databases
336d0 20 68 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e 67   having encoding
336e0 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30   E..**.** {H1660
336f0 34 7d 20 53 51 4c 69 74 65 20 75 6e 64 65 72 73  4} SQLite unders
33700 74 61 6e 64 73 20 74 68 65 20 58 20 70 61 72 61  tands the X para
33710 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  meter to.**     
33720 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72       [sqlite3_cr
33730 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
33740 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20  2(B,X,E,P,F,D)] 
33750 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  as a zero-termin
33760 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
33770 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e   UTF-8 string in
33780 20 77 68 69 63 68 20 63 61 73 65 20 69 73 20 69   which case is i
33790 67 6e 6f 72 65 64 20 66 6f 72 20 41 53 43 49 49  gnored for ASCII
337a0 20 63 68 61 72 61 63 74 65 72 73 20 61 6e 64 0a   characters and.
337b0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 73  **          is s
337c0 69 67 6e 69 66 69 63 61 6e 74 20 66 6f 72 20 6e  ignificant for n
337d0 6f 6e 2d 41 53 43 49 49 20 63 68 61 72 61 63 74  on-ASCII charact
337e0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  ers..**.** {H166
337f0 30 36 7d 20 53 75 63 63 65 73 73 69 76 65 20 63  06} Successive c
33800 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
33810 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
33820 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
33830 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  )].**          w
33840 69 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c  ith the same val
33850 75 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61 6e  ues for B, X, an
33860 64 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70 72  d E, override pr
33870 69 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20  ior values.**   
33880 20 20 20 20 20 20 20 6f 66 20 50 2c 20 46 2c 20         of P, F, 
33890 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  and D..**.** {H1
338a0 36 36 30 39 7d 20 49 66 20 74 68 65 20 64 65 73  6609} If the des
338b0 74 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 71  tructor D in [sq
338c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
338d0 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c  lation_v2(B,X,E,
338e0 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20  P,F,D)].**      
338f0 20 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20      is not NULL 
33900 74 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c 65  then it is calle
33910 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
33920 50 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20  P when the.**   
33930 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67         collating
33940 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f   function is dro
33950 70 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  pped by SQLite..
33960 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 32 7d 20 41  **.** {H16612} A
33970 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
33980 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77  ion is dropped w
33990 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c 6f  hen it is overlo
339a0 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  aded..**.** {H16
339b0 36 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67  615} A collating
339c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f   function is dro
339d0 70 70 65 64 20 77 68 65 6e 20 74 68 65 20 64 61  pped when the da
339e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
339f0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  n.**          is
33a00 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73   closed using [s
33a10 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
33a20 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 38 7d 20  .**.** {H16618} 
33a30 54 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69 6e  The pointer P in
33a40 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33a50 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
33a60 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
33a70 20 20 20 20 20 20 20 20 69 73 20 70 61 73 73 65          is passe
33a80 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
33a90 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
33aa0 20 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 73   to the comparis
33ab0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  on.**          f
33ac0 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c  unction F for al
33ad0 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
33ae0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a  ocations of F..*
33af0 2a 0a 2a 2a 20 7b 48 31 36 36 32 31 7d 20 41 20  *.** {H16621} A 
33b00 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
33b10 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
33b20 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 73  n(B,X,E,P,F)] is
33b30 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20   exactly.**     
33b40 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73       the same as
33b50 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
33b60 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33b70 74 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a  tion_v2()] with.
33b80 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
33b90 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20  same parameters 
33ba0 61 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 72  and a NULL destr
33bb0 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  uctor..**.** {H1
33bc0 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20  6624} Following 
33bd0 61 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  a [sqlite3_creat
33be0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
33bf0 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a  ,X,E,P,F,D)],.**
33c00 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65            SQLite
33c10 20 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61 72   uses the compar
33c20 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 20  ison function F 
33c30 66 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f 6d  for all text com
33c40 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20  parison.**      
33c50 20 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f      operations o
33c60 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
33c70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 6f 6e  connection] B on
33c80 20 74 65 78 74 20 76 61 6c 75 65 73 20 74 68 61   text values tha
33c90 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73  t.**          us
33ca0 65 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  e the collating 
33cb0 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 64 20 58  sequence named X
33cc0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 37 7d  ..**.** {H16627}
33cd0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   The [sqlite3_cr
33ce0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
33cf0 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f 72  (B,X,E,P,F)] wor
33d00 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  ks the same.**  
33d10 20 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c 69          as [sqli
33d20 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33d30 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d  tion(B,X,E,P,F)]
33d40 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
33d50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
33d60 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73  lation name X is
33d70 20 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20 55   understood as U
33d80 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20  TF-16 in native 
33d90 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
33da0 20 20 20 20 20 20 20 69 6e 73 74 65 61 64 20 6f         instead o
33db0 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b  f UTF-8..**.** {
33dc0 48 31 36 36 33 30 7d 20 57 68 65 6e 20 6d 75 6c  H16630} When mul
33dd0 74 69 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f 6e  tiple comparison
33de0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61   functions are a
33df0 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 74 68 65  vailable for the
33e00 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
33e10 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75    collating sequ
33e20 65 6e 63 65 2c 20 53 51 4c 69 74 65 20 63 68 6f  ence, SQLite cho
33e30 6f 73 65 73 20 74 68 65 20 6f 6e 65 20 77 68 6f  oses the one who
33e40 73 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  se text encoding
33e50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 71  .**          req
33e60 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20  uires the least 
33e70 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65 72  amount of conver
33e80 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64 65  sion from the de
33e90 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20  fault.**        
33ea0 20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20    text encoding 
33eb0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  of the database.
33ec0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
33ed0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33ee0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
33ef0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
33f00 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
33f10 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
33f20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
33f30 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
33f40 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
33f50 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
33f60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33f70 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
33f80 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
33f90 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
33fa0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
33fb0 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
33fc0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
33fd0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
33fe0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
33ff0 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
34000 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  y)(void*).);.int
34010 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34020 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
34030 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
34040 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
34050 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
34060 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
34070 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
34080 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
34090 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
340a0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
340b0 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
340c0 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20  eeded Callbacks 
340d0 7b 48 31 36 37 30 30 7d 20 3c 53 32 30 33 30 30  {H16700} <S20300
340e0 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  >.**.** To avoid
340f0 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
34100 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
34110 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
34120 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
34130 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
34140 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
34150 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
34160 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
34170 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
34180 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
34190 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76  be called whenev
341a0 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
341b0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
341c0 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
341d0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
341e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
341f0 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
34200 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
34210 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
34220 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
34230 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
34240 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
34250 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
34260 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
34270 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
34280 20 7b 48 31 36 37 30 33 7d 20 49 66 20 73 71 6c   {H16703} If sql
34290 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
342a0 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
342b0 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
342c0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
342d0 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
342e0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
342f0 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  r..** A call to 
34300 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  either function 
34310 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69  replaces any exi
34320 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a  sting callback..
34330 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
34340 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
34350 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
34360 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
34370 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
34380 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
34390 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
343a0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
343b0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
343c0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
343d0 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
343e0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
343f0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
34400 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
34410 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
34420 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
34430 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
34440 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
34450 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
34460 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
34470 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
34480 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
34490 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
344a0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
344b0 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
344c0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
344d0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
344e0 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
344f0 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a   sequence..**.**
34500 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
34510 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
34520 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
34530 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
34540 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
34550 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
34560 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
34570 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
34580 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
34590 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
345a0 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  ion_v2()]..**.**
345b0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
345c0 2a 2a 20 7b 48 31 36 37 30 32 7d 20 41 20 73 75  ** {H16702} A su
345d0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
345e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
345f0 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c 46  ion_needed(D,P,F
34600 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
34610 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  r [sqlite3_colla
34620 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44 2c  tion_needed16(D,
34630 50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a 20  P,F)] causes.** 
34640 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 61           the [da
34650 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34660 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20 63  n] D to invoke c
34670 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20 66  allback F with f
34680 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  irst.**         
34690 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65   parameter P whe
346a0 6e 65 76 65 72 20 69 74 20 6e 65 65 64 73 20 61  never it needs a
346b0 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63   comparison func
346c0 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20 20  tion for a.**   
346d0 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67         collating
346e0 20 73 65 71 75 65 6e 63 65 20 74 68 61 74 20 69   sequence that i
346f0 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77 20  t does not know 
34700 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  about..**.** {H1
34710 36 37 30 34 7d 20 45 61 63 68 20 73 75 63 63 65  6704} Each succe
34720 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
34730 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
34740 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a 2a  _needed()] or.**
34750 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
34760 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
34770 64 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69 64  ded16()] overrid
34780 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  es the callback 
34790 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20  registered.**   
347a0 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61         on the sa
347b0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
347c0 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69 6f  nection] by prio
347d0 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68 65  r calls to eithe
347e0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  r.**          in
347f0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b  terface..**.** {
34800 48 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d 65  H16706} The name
34810 20 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 65   of the requeste
34820 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  d collating func
34830 74 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20 74  tion passed in t
34840 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 34  he.**          4
34850 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
34860 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
34870 69 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65 20  in UTF-8 if the 
34880 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
34890 20 20 20 20 20 77 61 73 20 72 65 67 69 73 74 65       was registe
348a0 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  red using [sqlit
348b0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
348c0 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  ded()] and.**   
348d0 20 20 20 20 20 20 20 69 73 20 69 6e 20 55 54 46         is in UTF
348e0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
348f0 6f 72 64 65 72 20 69 66 20 74 68 65 20 63 61 6c  order if the cal
34900 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20 20  lback was.**    
34910 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
34920 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
34930 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
34940 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
34950 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
34960 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
34970 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
34980 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
34990 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
349a0 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
349b0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
349c0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
349d0 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
349e0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
349f0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
34a00 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
34a10 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
34a20 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
34a30 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
34a40 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
34a50 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
34a60 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
34a70 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
34a80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
34a90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
34aa0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
34ab0 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
34ac0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
34ad0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
34ae0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
34af0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
34b00 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
34b10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34b20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
34b30 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
34b40 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
34b50 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
34b60 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
34b70 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
34b80 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
34b90 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
34ba0 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
34bb0 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
34bc0 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
34bd0 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
34be0 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
34bf0 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
34c00 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
34c10 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
34c20 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
34c30 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
34c40 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
34c50 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
34c60 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
34c70 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
34c80 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
34c90 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
34ca0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
34cb0 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
34cc0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
34cd0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
34ce0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
34cf0 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
34d00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34d10 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
34d20 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
34d30 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53 34  ime {H10530} <S4
34d40 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0410>.**.** The 
34d50 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
34d60 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
34d70 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
34d80 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78  ad to suspend ex
34d90 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61  ecution.** for a
34da0 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72  t least a number
34db0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
34dc0 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74   specified in it
34dd0 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  s parameter..**.
34de0 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74  ** If the operat
34df0 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20  ing system does 
34e00 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65  not support slee
34e10 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a  p requests with.
34e20 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74  ** millisecond t
34e30 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20  ime resolution, 
34e40 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69  then the time wi
34e50 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70  ll be rounded up
34e60 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65   to.** the neare
34e70 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
34e80 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
34e90 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
34ea0 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65  ctually.** reque
34eb0 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70  sted from the op
34ec0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
34ed0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
34ee0 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
34ef0 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
34f00 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
34f10 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
34f20 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
34f30 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
34f40 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
34f50 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
34f60 2a 20 7b 48 31 30 35 33 33 7d 20 54 68 65 20 5b  * {H10533} The [
34f70 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29  sqlite3_sleep(M)
34f80 5d 20 69 6e 74 65 72 66 61 63 65 20 69 6e 76 6f  ] interface invo
34f90 6b 65 73 20 74 68 65 20 78 53 6c 65 65 70 0a 2a  kes the xSleep.*
34fa0 2a 20 20 20 20 20 20 20 20 20 20 6d 65 74 68 6f  *          metho
34fb0 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
34fc0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c 56 46   [sqlite3_vfs|VF
34fd0 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  S] in order to.*
34fe0 2a 20 20 20 20 20 20 20 20 20 20 73 75 73 70 65  *          suspe
34ff0 6e 64 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  nd execution of 
35000 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
35010 61 64 20 66 6f 72 20 61 74 20 6c 65 61 73 74 0a  ad for at least.
35020 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20 6d 69  **          M mi
35030 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a  lliseconds..**.*
35040 2a 20 7b 48 31 30 35 33 36 7d 20 54 68 65 20 5b  * {H10536} The [
35050 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29  sqlite3_sleep(M)
35060 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
35070 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
35080 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 69  f.**          mi
35090 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
350a0 65 65 70 20 61 63 74 75 61 6c 6c 79 20 72 65 71  eep actually req
350b0 75 65 73 74 65 64 20 6f 66 20 74 68 65 20 6f 70  uested of the op
350c0 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20  erating.**      
350d0 20 20 20 20 73 79 73 74 65 6d 2c 20 77 68 69 63      system, whic
350e0 68 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65  h might be large
350f0 72 20 74 68 61 6e 20 74 68 65 20 70 61 72 61 6d  r than the param
35100 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73  eter M..*/.int s
35110 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74  qlite3_sleep(int
35120 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35130 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
35140 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
35150 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b  emporary Files {
35160 48 31 30 33 31 30 7d 20 3c 53 32 30 30 30 30 3e  H10310} <S20000>
35170 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67  .**.** If this g
35180 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
35190 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
351a0 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
351b0 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
351c0 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
351d0 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
351e0 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72   then all tempor
351f0 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65  ary files.** cre
35200 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77  ated by SQLite w
35210 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e  ill be placed in
35220 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e   that directory.
35230 20 20 49 66 20 74 68 69 73 20 76 61 72 69 61 62    If this variab
35240 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  le.** is a NULL 
35250 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
35260 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20  Lite performs a 
35270 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
35280 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d  propriate.** tem
35290 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65  porary file dire
352a0 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
352b0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d  is not safe to m
352c0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
352d0 62 6c 65 20 6f 6e 63 65 20 61 20 5b 64 61 74 61  ble once a [data
352e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
352f0 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 6f 70 65  .** has been ope
35300 6e 65 64 2e 20 20 49 74 20 69 73 20 69 6e 74 65  ned.  It is inte
35310 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
35320 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
35330 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
35340 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
35350 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
35360 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
35370 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
35380 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
35390 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20 75  all and remain u
353a0 6e 63 68 61 6e 67 65 64 20 74 68 65 72 65 61 66  nchanged thereaf
353b0 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ter..*/.SQLITE_E
353c0 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
353d0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
353e0 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
353f0 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75  REF: Test For Au
35400 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b  to-Commit Mode {
35410 48 31 32 39 33 30 7d 20 3c 53 36 30 32 30 30 3e  H12930} <S60200>
35420 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
35430 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a  utocommit mode}.
35440 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
35450 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
35460 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
35470 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
35480 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
35490 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
354a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
354b0 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
354c0 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
354d0 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 75 74  spectively.  Aut
354e0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
354f0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
35500 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  * Autocommit mod
35510 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
35520 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65   a [BEGIN] state
35530 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d  ment..** Autocom
35540 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65  mit mode is re-e
35550 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d  nabled by a [COM
35560 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43  MIT] or [ROLLBAC
35570 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72  K]..**.** If cer
35580 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72  tain kinds of er
35590 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20  rors occur on a 
355a0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
355b0 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65   a multi-stateme
355c0 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  nt.** transactio
355d0 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64  n (errors includ
355e0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c  ing [SQLITE_FULL
355f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ], [SQLITE_IOERR
35600 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  ],.** [SQLITE_NO
35610 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55  MEM], [SQLITE_BU
35620 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  SY], and [SQLITE
35630 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65  _INTERRUPT]) the
35640 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63  n the.** transac
35650 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f  tion might be ro
35660 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
35670 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e  tically.  The on
35680 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e  ly way to.** fin
35690 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51  d out whether SQ
356a0 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
356b0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74  ly rolled back t
356c0 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61  he transaction a
356d0 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  fter.** an error
356e0 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20   is to use this 
356f0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
35700 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
35710 2a 20 7b 48 31 32 39 33 31 7d 20 54 68 65 20 5b  * {H12931} The [
35720 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
35730 63 6f 6d 6d 69 74 28 44 29 5d 20 69 6e 74 65 72  commit(D)] inter
35740 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e  face returns non
35750 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20 20 20 20  -zero or.**     
35760 20 20 20 20 20 7a 65 72 6f 20 69 66 20 74 68 65       zero if the
35770 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35780 63 74 69 6f 6e 5d 20 44 20 69 73 20 6f 72 20 69  ction] D is or i
35790 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
357a0 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  mit.**          
357b0 6d 6f 64 65 2c 20 72 65 73 70 65 63 74 69 76 65  mode, respective
357c0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33  ly..**.** {H1293
357d0 32 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  2} Autocommit mo
357e0 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61  de is on by defa
357f0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ult..**.** {H129
35800 33 33 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  33} Autocommit m
35810 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
35820 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c 20  by a successful 
35830 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
35840 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 34  t..**.** {H12934
35850 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  } Autocommit mod
35860 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 20  e is enabled by 
35870 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b 43 4f  a successful [CO
35880 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
35890 43 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  CK].**          
358a0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
358b0 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
358c0 0a 2a 2a 20 7b 41 31 32 39 33 36 7d 20 49 66 20  .** {A12936} If 
358d0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
358e0 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
358f0 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
35900 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
35910 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74           connect
35920 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
35930 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
35940 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
35950 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20  rn value.**     
35960 20 20 20 20 20 69 73 20 75 6e 64 65 66 69 6e 65       is undefine
35970 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
35980 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
35990 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
359a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
359b0 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48  d The Database H
359c0 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61  andle Of A Prepa
359d0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48  red Statement {H
359e0 31 33 31 32 30 7d 20 3c 53 36 30 36 30 30 3e 0a  13120} <S60600>.
359f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
35a00 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65  3_db_handle inte
35a10 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
35a20 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
35a30 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a  ection] handle.*
35a40 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72  * to which a [pr
35a50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
35a60 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 54 68 65 20  ] belongs.  The 
35a70 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
35a80 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 73  returned by.** s
35a90 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
35aa0 20 69 73 20 74 68 65 20 73 61 6d 65 20 64 61 74   is the same dat
35ab0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61  abase handle tha
35ac0 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20  t was the first 
35ad0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
35ae0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
35af0 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28  are_v2()] call (
35b00 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  or its variants)
35b10 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74   that was used t
35b20 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20  o.** create the 
35b30 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
35b40 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
35b50 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
35b60 2a 2a 0a 2a 2a 20 7b 48 31 33 31 32 33 7d 20 54  **.** {H13123} T
35b70 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 68  he [sqlite3_db_h
35b80 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65 72 66  andle(S)] interf
35b90 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
35ba0 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
35bb0 20 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61    to the [databa
35bc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
35bd0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
35be0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
35bf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35c00 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65  nt] S..*/.sqlite
35c10 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
35c20 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
35c30 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
35c40 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
35c50 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
35c60 74 65 6d 65 6e 74 20 7b 48 31 33 31 34 30 7d 20  tement {H13140} 
35c70 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60600>.**.** T
35c80 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
35c90 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
35ca0 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65  to the next [pre
35cb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
35cc0 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20   after.** pStmt 
35cd0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
35ce0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
35cf0 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20  nnection] pDb.  
35d00 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
35d10 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
35d20 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35d30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
35d40 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
35d50 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
35d60 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
35d70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35d80 74 69 6f 6e 20 70 44 62 2e 20 20 49 66 20 6e 6f  tion pDb.  If no
35d90 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
35da0 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73  ent.** satisfies
35db0 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20   the conditions 
35dc0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
35dd0 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c   it returns NULL
35de0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
35df0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34  TS:.**.** {H1314
35e00 33 7d 20 49 66 20 44 20 69 73 20 61 20 5b 64 61  3} If D is a [da
35e10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35e20 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73 20 6f 6e  n] that holds on
35e30 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20  e or more.**    
35e40 20 20 20 20 20 20 75 6e 66 69 6e 61 6c 69 7a 65        unfinalize
35e50 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
35e60 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20 69 73  ements] and S is
35e70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
35e80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
35e90 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  n [sqlite3_next_
35ea0 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74  stmt(D, S)] rout
35eb0 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ine shall return
35ec0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
35ed0 20 20 20 20 20 20 20 74 6f 20 6f 6e 65 20 6f 66         to one of
35ee0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
35ef0 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
35f00 74 65 64 20 77 69 74 68 20 44 2e 0a 2a 2a 0a 2a  ted with D..**.*
35f10 2a 20 7b 48 31 33 31 34 36 7d 20 49 66 20 44 20  * {H13146} If D 
35f20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
35f30 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
35f40 68 6f 6c 64 73 20 6e 6f 20 75 6e 66 69 6e 61 6c  holds no unfinal
35f50 69 7a 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ized.**         
35f60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
35f70 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20 69 73 20  ments] and S is 
35f80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
35f90 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
35fa0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
35fb0 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69  tmt(D, S)] routi
35fc0 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  ne shall return 
35fd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
35fe0 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 39 7d 20 49  **.** {H13149} I
35ff0 66 20 53 20 69 73 20 61 20 5b 70 72 65 70 61 72  f S is a [prepar
36000 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
36010 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
36020 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
36030 20 20 20 20 20 20 20 20 20 61 6e 64 20 53 20 69           and S i
36040 73 20 6e 6f 74 20 74 68 65 20 6c 61 73 74 20 70  s not the last p
36050 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36060 74 20 69 6e 20 44 2c 20 74 68 65 6e 0a 2a 2a 20  t in D, then.** 
36070 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
36080 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53  3_next_stmt(D, S
36090 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c  )] routine shall
360a0 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65   return a pointe
360b0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  r.**          to
360c0 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72   the next prepar
360d0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ed statement in 
360e0 44 20 61 66 74 65 72 20 53 2e 0a 2a 2a 0a 2a 2a  D after S..**.**
360f0 20 7b 48 31 33 31 35 32 7d 20 49 66 20 53 20 69   {H13152} If S i
36100 73 20 74 68 65 20 6c 61 73 74 20 5b 70 72 65 70  s the last [prep
36110 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
36120 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
36130 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
36140 6e 65 63 74 69 6f 6e 5d 20 44 20 74 68 65 6e 20  nection] D then 
36150 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  the [sqlite3_nex
36160 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 0a 2a 2a  t_stmt(D, S)].**
36170 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e            routin
36180 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61  e shall return a
36190 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
361a0 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
361b0 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 31 35 34 7d  :.**.** {A13154}
361c0 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   The [database c
361d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74  onnection] point
361e0 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74  er D in a call t
361f0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
36200 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
36210 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65  (D,S)] must refe
36220 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74  r to an open dat
36230 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20  abase.**        
36240 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64    connection and
36250 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d   in particular m
36260 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c  ust not be a NUL
36270 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71  L pointer..*/.sq
36280 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69  lite3_stmt *sqli
36290 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71  te3_next_stmt(sq
362a0 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69  lite3 *pDb, sqli
362b0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
362c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
362d0 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
362e0 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
362f0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48  ion Callbacks {H
36300 31 32 39 35 30 7d 20 3c 53 36 30 34 30 30 3e 0a  12950} <S60400>.
36310 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
36320 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
36330 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
36340 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
36350 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
36360 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
36370 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
36380 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a  is committed..**
36390 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
363a0 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
363b0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
363c0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a  commit_hook().**
363d0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
363e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
363f0 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
36400 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
36410 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20  rollback_hook() 
36420 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
36430 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
36440 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
36450 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
36460 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
36470 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a  is committed..**
36480 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
36490 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
364a0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
364b0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a  commit_hook().**
364c0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
364d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
364e0 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
364f0 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72 67  .** The pArg arg
36500 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
36510 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
36520 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 20 74  allback..** If t
36530 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
36540 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
36550 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f  ction returns no
36560 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  n-zero,.** then 
36570 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
36580 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
36590 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49  ollback..**.** I
365a0 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69  f another functi
365b0 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c  on was previousl
365c0 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74  y registered, it
365d0 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20  s.** pArg value 
365e0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
365f0 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
36600 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
36610 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55  Registering a NU
36620 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  LL function disa
36630 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  bles the callbac
36640 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  k..**.** For the
36650 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
36660 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
36670 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
36680 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c  have been.** rol
36690 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65  led back if an e
366a0 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43  xplicit "ROLLBAC
366b0 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  K" statement is 
366c0 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20  executed, or.** 
366d0 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73  an error or cons
366e0 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e  traint causes an
366f0 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61   implicit rollba
36700 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20  ck to occur..** 
36710 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c  The rollback cal
36720 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76  lback is not inv
36730 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61  oked if a transa
36740 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f  ction is.** auto
36750 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
36760 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68   back because th
36770 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
36780 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
36790 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b  .** The rollback
367a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
367b0 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72   invoked if a tr
367c0 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20  ansaction is.** 
367d0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61  rolled back beca
367e0 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c  use a commit cal
367f0 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e  lback returned n
36800 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64  on-zero..** <tod
36810 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73  o> Check on this
36820 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 49   </todo>.**.** I
36830 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
36840 20 7b 48 31 32 39 35 31 7d 20 54 68 65 20 5b 73   {H12951} The [s
36850 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
36860 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72  ok(D,F,P)] inter
36870 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 74  face registers t
36880 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
36890 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
368a0 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   F to be invoked
368b0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
368c0 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20   whenever.**    
368d0 20 20 20 20 20 20 61 20 74 72 61 6e 73 61 63 74        a transact
368e0 69 6f 6e 20 63 6f 6d 6d 69 74 73 20 6f 6e 20 74  ion commits on t
368f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
36900 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
36910 2a 20 7b 48 31 32 39 35 32 7d 20 54 68 65 20 5b  * {H12952} The [
36920 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
36930 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
36940 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
36950 65 20 50 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  e P argument.** 
36960 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 74 68           from th
36970 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
36980 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 5b 64  with the same [d
36990 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
369a0 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20  on] D,.**       
369b0 20 20 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68     or NULL on th
369c0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72  e first call for
369d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
369e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
369f0 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  n D..**.** {H129
36a00 35 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  53} Each call to
36a10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   [sqlite3_commit
36a20 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69  _hook()] overwri
36a30 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  tes the callback
36a40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
36a50 69 73 74 65 72 65 64 20 62 79 20 70 72 69 6f 72  istered by prior
36a60 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48   calls..**.** {H
36a70 31 32 39 35 34 7d 20 49 66 20 74 68 65 20 46 20  12954} If the F 
36a80 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
36a90 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
36aa0 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c  (D,F,P)] is NULL
36ab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
36ac0 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  n the commit hoo
36ad0 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61  k callback is ca
36ae0 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61  nceled and no ca
36af0 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
36b00 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68     is invoked wh
36b10 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  en a transaction
36b20 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20   commits..**.** 
36b30 7b 48 31 32 39 35 35 7d 20 49 66 20 74 68 65 20  {H12955} If the 
36b40 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20  commit callback 
36b50 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
36b60 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
36b70 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
36b80 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
36b90 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
36ba0 20 7b 48 31 32 39 36 31 7d 20 54 68 65 20 5b 73   {H12961} The [s
36bb0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
36bc0 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
36bd0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
36be0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
36bf0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
36c00 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on F to be invok
36c10 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
36c20 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20   P whenever.**  
36c30 20 20 20 20 20 20 20 20 61 20 74 72 61 6e 73 61          a transa
36c40 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b  ction rolls back
36c50 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
36c60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
36c70 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 32 7d 20  .**.** {H12962} 
36c80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c  The [sqlite3_rol
36c90 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50  lback_hook(D,F,P
36ca0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
36cb0 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20 20  urns the P.**   
36cc0 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20         argument 
36cd0 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
36ce0 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20  s call with the 
36cf0 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
36d00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36d10 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
36d20 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63  L on the first c
36d30 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
36d40 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
36d50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36d60 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tion D..**.** {H
36d70 31 32 39 36 33 7d 20 45 61 63 68 20 63 61 6c 6c  12963} Each call
36d80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c   to [sqlite3_rol
36d90 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76  lback_hook()] ov
36da0 65 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c  erwrites the cal
36db0 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
36dc0 20 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20    registered by 
36dd0 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a  prior calls..**.
36de0 2a 2a 20 7b 48 31 32 39 36 34 7d 20 49 66 20 74  ** {H12964} If t
36df0 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f  he F argument to
36e00 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
36e10 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  ck_hook(D,F,P)] 
36e20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20  is NULL.**      
36e30 20 20 20 20 74 68 65 6e 20 74 68 65 20 72 6f 6c      then the rol
36e40 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62  lback hook callb
36e50 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 65 64 20  ack is canceled 
36e60 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a  and no callback.
36e70 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69  **          is i
36e80 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72  nvoked when a tr
36e90 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20  ansaction rolls 
36ea0 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  back..*/.void *s
36eb0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
36ec0 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ok(sqlite3*, int
36ed0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
36ee0 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
36ef0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
36f00 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
36f10 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a  )(void *), void*
36f20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36f30 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20  EF: Data Change 
36f40 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
36f50 6c 62 61 63 6b 73 20 7b 48 31 32 39 37 30 7d 20  lbacks {H12970} 
36f60 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60400>.**.** T
36f70 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  he sqlite3_updat
36f80 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  e_hook() interfa
36f90 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
36fa0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
36fb0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
36fc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36fd0 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  n] identified by
36fe0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
36ff0 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76  ent.** to be inv
37000 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
37010 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20  row is updated, 
37020 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
37030 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ted..** Any call
37040 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
37050 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74  evious call to t
37060 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
37070 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
37080 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37090 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
370a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
370b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
370c0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
370d0 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
370e0 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
370f0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
37100 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
37110 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
37120 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c  ument to the cal
37130 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
37140 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67  of the third arg
37150 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
37160 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
37170 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
37180 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65   callback argume
37190 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
371a0 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
371b0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a  QLITE_DELETE],.*
371c0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  * or [SQLITE_UPD
371d0 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20  ATE], depending 
371e0 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
371f0 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
37200 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20   callback.** to 
37210 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54  be invoked..** T
37220 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
37230 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
37240 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
37250 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74  ntain pointers t
37260 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
37270 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65  e and table name
37280 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
37290 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a  affected row..**
372a0 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62   The final callb
372b0 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
372c0 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
372d0 65 20 72 6f 77 2e 20 49 6e 20 74 68 65 20 63 61  e row. In the ca
372e0 73 65 20 6f 66 0a 2a 2a 20 61 6e 20 75 70 64 61  se of.** an upda
372f0 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  te, this is the 
37300 72 6f 77 69 64 20 61 66 74 65 72 20 74 68 65 20  rowid after the 
37310 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61  update takes pla
37320 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70  ce..**.** The up
37330 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74  date hook is not
37340 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e   invoked when in
37350 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61  ternal system ta
37360 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69  bles are.** modi
37370 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74  fied (i.e. sqlit
37380 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c  e_master and sql
37390 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a  ite_sequence)..*
373a0 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
373b0 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65  function was pre
373c0 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
373d0 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c  ed, its pArg val
373e0 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ue.** is returne
373f0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55  d.  Otherwise NU
37400 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  LL is returned..
37410 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
37420 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 31 7d  :.**.** {H12971}
37430 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70   The [sqlite3_up
37440 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  date_hook(D,F,P)
37450 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ] interface caus
37460 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
37470 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63  **          func
37480 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76  tion F to be inv
37490 6f 6b 65 64 20 77 69 74 68 20 66 69 72 73 74 20  oked with first 
374a0 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e  parameter P when
374b0 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ever.**         
374c0 20 61 20 74 61 62 6c 65 20 72 6f 77 20 69 73 20   a table row is 
374d0 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
374e0 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 6f  ed, or deleted o
374f0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
37500 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37510 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
37520 20 7b 48 31 32 39 37 33 7d 20 54 68 65 20 5b 73   {H12973} The [s
37530 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
37540 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72  ok(D,F,P)] inter
37550 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
37560 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20   value.**       
37570 20 20 20 6f 66 20 50 20 66 6f 72 20 74 68 65 20     of P for the 
37580 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 6e  previous call on
37590 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
375a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
375b0 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  D,.**          o
375c0 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68 65 20 66  r NULL for the f
375d0 69 72 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  irst call..**.**
375e0 20 7b 48 31 32 39 37 35 7d 20 49 66 20 74 68 65   {H12975} If the
375f0 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c   update hook cal
37600 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73 71 6c 69  lback F in [sqli
37610 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
37620 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20 20 20 20  D,F,P)].**      
37630 20 20 20 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e      is NULL then
37640 20 74 68 65 20 6e 6f 20 75 70 64 61 74 65 20 63   the no update c
37650 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6d 61 64  allbacks are mad
37660 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 37  e..**.** {H12977
37670 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
37680 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
37690 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 6f 76 65 72  ook(D,F,P)] over
376a0 72 69 64 65 73 20 70 72 69 6f 72 20 63 61 6c 6c  rides prior call
376b0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  s.**          to
376c0 20 74 68 65 20 73 61 6d 65 20 69 6e 74 65 72 66   the same interf
376d0 61 63 65 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ace on the same 
376e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
376f0 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
37700 48 31 32 39 37 39 7d 20 54 68 65 20 75 70 64 61  H12979} The upda
37710 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  te hook callback
37720 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
37730 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79  when internal sy
37740 73 74 65 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20  stem.**         
37750 20 74 61 62 6c 65 73 20 73 75 63 68 20 61 73 20   tables such as 
37760 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e  sqlite_master an
37770 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63  d sqlite_sequenc
37780 65 20 61 72 65 20 6d 6f 64 69 66 69 65 64 2e 0a  e are modified..
37790 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38 31 7d 20 54  **.** {H12981} T
377a0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
377b0 74 65 72 20 74 6f 20 74 68 65 20 75 70 64 61 74  ter to the updat
377c0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  e callback.**   
377d0 20 20 20 20 20 20 20 69 73 20 6f 6e 65 20 6f 66         is one of
377e0 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d   [SQLITE_INSERT]
377f0 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  , [SQLITE_DELETE
37800 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  ] or [SQLITE_UPD
37810 41 54 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ATE],.**        
37820 20 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74    depending on t
37830 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  he operation tha
37840 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c  t caused the cal
37850 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f  lback to be invo
37860 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ked..**.** {H129
37870 38 33 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e  83} The third an
37880 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  d fourth argumen
37890 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ts to the callba
378a0 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74  ck contain point
378b0 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
378c0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
378d0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
378e0 20 77 68 69 63 68 20 61 72 65 20 74 68 65 20 6e   which are the n
378f0 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20  ames of the.**  
37900 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
37910 20 61 6e 64 20 74 61 62 6c 65 20 74 68 61 74 20   and table that 
37920 69 73 20 62 65 69 6e 67 20 75 70 64 61 74 65 64  is being updated
37930 2e 0a 0a 2a 2a 20 7b 48 31 32 39 38 35 7d 20 54  ...** {H12985} T
37940 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63  he final callbac
37950 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  k parameter is t
37960 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20  he rowid of the 
37970 72 6f 77 20 61 66 74 65 72 0a 2a 2a 20 20 20 20  row after.**    
37980 20 20 20 20 20 20 74 68 65 20 63 68 61 6e 67 65        the change
37990 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64   occurs..*/.void
379a0 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   *sqlite3_update
379b0 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33  _hook(.  sqlite3
379c0 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
379d0 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63  id *,int ,char c
379e0 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73  onst *,char cons
379f0 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  t *,sqlite3_int6
37a00 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a  4),.  void*.);..
37a10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37a20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
37a30 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20 43  e Shared Pager C
37a40 61 63 68 65 20 7b 48 31 30 33 33 30 7d 20 3c 53  ache {H10330} <S
37a50 33 30 39 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  30900>.** KEYWOR
37a60 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68  DS: {shared cach
37a70 65 7d 20 7b 73 68 61 72 65 64 20 63 61 63 68 65  e} {shared cache
37a80 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69   mode}.**.** Thi
37a90 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  s routine enable
37aa0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
37ab0 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65  e sharing of the
37ac0 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a   database cache.
37ad0 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61  ** and schema da
37ae0 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65  ta structures be
37af0 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20  tween [database 
37b00 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e  connection | con
37b10 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20  nections].** to 
37b20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
37b30 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e  e. Sharing is en
37b40 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67  abled if the arg
37b50 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a  ument is true.**
37b60 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66   and disabled if
37b70 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   the argument is
37b80 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61   false..**.** Ca
37b90 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65  che sharing is e
37ba0 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62  nabled and disab
37bb0 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72  led for an entir
37bc0 65 20 70 72 6f 63 65 73 73 2e 20 7b 45 4e 44 7d  e process. {END}
37bd0 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68  .** This is a ch
37be0 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74  ange as of SQLit
37bf0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e  e version 3.5.0.
37c00 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f   In prior versio
37c10 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a  ns of SQLite,.**
37c20 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61   sharing was ena
37c30 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
37c40 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64   for each thread
37c50 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
37c60 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61  ** The cache sha
37c70 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79  ring mode set by
37c80 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
37c90 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73  effects all subs
37ca0 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
37cb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
37cc0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
37cd0 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73  en_v2()], and [s
37ce0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
37cf0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61  ..** Existing da
37d00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37d10 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20  ns continue use 
37d20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  the sharing mode
37d30 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20  .** that was in 
37d40 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69  effect at the ti
37d50 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65  me they were ope
37d60 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75  ned..**.** Virtu
37d70 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74  al tables cannot
37d80 20 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20   be used with a 
37d90 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 57  shared cache.  W
37da0 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  hen shared.** ca
37db0 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  che is enabled, 
37dc0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
37dd0 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50  ate_module()] AP
37de0 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74  I used to regist
37df0 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  er.** virtual ta
37e00 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73  bles will always
37e10 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
37e20 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
37e30 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
37e40 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
37e50 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61  ed cache was ena
37e60 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
37e70 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
37e80 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64  .  An [error cod
37e90 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f  e] is returned o
37ea0 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
37eb0 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  Shared cache is 
37ec0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
37ed0 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69  ult. But this mi
37ee0 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ght change in.**
37ef0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
37f00 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70   of SQLite.  App
37f10 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63  lications that c
37f20 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64  are about shared
37f30 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e  .** cache settin
37f40 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20  g should set it 
37f50 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a  explicitly..**.*
37f60 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
37f70 0a 2a 2a 20 7b 48 31 30 33 33 31 7d 20 41 20 73  .** {H10331} A s
37f80 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
37f90 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
37fa0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
37fb0 61 63 68 65 28 42 29 5d 0a 2a 2a 20 20 20 20 20  ache(B)].**     
37fc0 20 20 20 20 20 77 69 6c 6c 20 65 6e 61 62 6c 65       will enable
37fd0 20 6f 72 20 64 69 73 61 62 6c 65 20 73 68 61 72   or disable shar
37fe0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 20 66 6f  ed cache mode fo
37ff0 72 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  r any subsequent
38000 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ly.**          c
38010 72 65 61 74 65 64 20 5b 64 61 74 61 62 61 73 65  reated [database
38020 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 20   connection] in 
38030 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
38040 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 36 7d  ..**.** {H10336}
38050 20 57 68 65 6e 20 73 68 61 72 65 64 20 63 61 63   When shared cac
38060 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74  he is enabled, t
38070 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
38080 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 0a 2a 2a 20  te_module()].** 
38090 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
380a0 63 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  ce will always r
380b0 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a  eturn an error..
380c0 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 37 7d 20 54  **.** {H10337} T
380d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  he [sqlite3_enab
380e0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
380f0 42 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  B)] interface re
38100 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
38110 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66    [SQLITE_OK] if
38120 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61   shared cache wa
38130 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  s enabled or dis
38140 61 62 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c  abled successful
38150 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33  ly..**.** {H1033
38160 39 7d 20 53 68 61 72 65 64 20 63 61 63 68 65 20  9} Shared cache 
38170 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
38180 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73  efault..*/.int s
38190 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
381a0 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b  ared_cache(int);
381b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
381c0 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65  : Attempt To Fre
381d0 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 20 7b 48  e Heap Memory {H
381e0 31 37 33 34 30 7d 20 3c 53 33 30 32 32 30 3e 0a  17340} <S30220>.
381f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
38200 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
38210 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
38220 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20  empts to free N 
38230 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70  bytes.** of heap
38240 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c   memory by deall
38250 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65  ocating non-esse
38260 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ntial memory all
38270 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64  ocations.** held
38280 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
38290 20 6c 69 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20   library. {END} 
382a0 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20   Memory used to 
382b0 63 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a  cache database.*
382c0 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f  * pages to impro
382d0 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69  ve performance i
382e0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
382f0 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
38300 6d 6f 72 79 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  mory..** sqlite3
38310 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
38320 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  ) returns the nu
38330 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63  mber of bytes ac
38340 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a  tually freed,.**
38350 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20   which might be 
38360 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61  more or less tha
38370 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71  n the amount req
38380 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  uested..**.** IN
38390 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
383a0 7b 48 31 37 33 34 31 7d 20 54 68 65 20 5b 73 71  {H17341} The [sq
383b0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
383c0 6d 6f 72 79 28 4e 29 5d 20 69 6e 74 65 72 66 61  mory(N)] interfa
383d0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a  ce attempts to.*
383e0 2a 20 20 20 20 20 20 20 20 20 20 66 72 65 65 20  *          free 
383f0 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 20  N bytes of heap 
38400 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f  memory by deallo
38410 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e  cating non-essen
38420 74 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  tial.**         
38430 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
38440 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65 20  ons held by the 
38450 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79  database library
38460 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 33 34 32 7d  ..**.** {H16342}
38470 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
38480 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d  lease_memory(N)]
38490 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
384a0 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ber.**          
384b0 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c  of bytes actuall
384c0 79 20 66 72 65 65 64 2c 20 77 68 69 63 68 20 6d  y freed, which m
384d0 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
384e0 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  less.**         
384f0 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74   than the amount
38500 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a 69   requested..*/.i
38510 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  nt sqlite3_relea
38520 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a  se_memory(int);.
38530 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
38540 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20   Impose A Limit 
38550 4f 6e 20 48 65 61 70 20 53 69 7a 65 20 7b 48 31  On Heap Size {H1
38560 37 33 35 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a  7350} <S30220>.*
38570 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
38580 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
38590 28 29 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61  () interface pla
385a0 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d  ces a "soft" lim
385b0 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d 6f  it.** on the amo
385c0 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  unt of heap memo
385d0 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61  ry that may be a
385e0 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
385f0 74 65 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  te..** If an int
38600 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e  ernal allocation
38610 20 69 73 20 72 65 71 75 65 73 74 65 64 20 74 68   is requested th
38620 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20  at would exceed 
38630 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61 70  the.** soft heap
38640 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33   limit, [sqlite3
38650 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
38660 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  )] is invoked on
38670 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 69 6d  e or.** more tim
38680 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f  es to free up so
38690 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20  me space before 
386a0 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  the allocation i
386b0 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a  s performed..**.
386c0 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20  ** The limit is 
386d0 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62  called "soft", b
386e0 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c 69 74  ecause if [sqlit
386f0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
38700 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20 66  y()].** cannot f
38710 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d  ree sufficient m
38720 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74  emory to prevent
38730 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20   the limit from 
38740 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a  being exceeded,.
38750 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73  ** the memory is
38760 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61   allocated anywa
38770 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e  y and the curren
38780 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  t operation proc
38790 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65  eeds..**.** A ne
387a0 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76  gative or zero v
387b0 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73  alue for N means
387c0 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e   that there is n
387d0 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  o soft heap limi
387e0 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  t and.** [sqlite
387f0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
38800 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65  ()] will only be
38810 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d   called when mem
38820 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 65 64  ory is exhausted
38830 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  ..** The default
38840 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73   value for the s
38850 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
38860 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51  s zero..**.** SQ
38870 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73  Lite makes a bes
38880 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f  t effort to hono
38890 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  r the soft heap 
388a0 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 74 20 69 66  limit..** But if
388b0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
388c0 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65 20 68  imit cannot be h
388d0 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 69 6f  onored, executio
388e0 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e  n will.** contin
388f0 75 65 20 77 69 74 68 6f 75 74 20 65 72 7