/ Hex Artifact Content
Login

Artifact db24c33101337693d5930da8d31b0ca21e266447:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20  r changes if.** 
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29  cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69   $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 33 37 39 20 32 30 30 38 2f 30  n,v 1.379 2008/0
05f0: 37 2f 32 35 20 30 38 3a 34 39 3a 30 30 20 64 61  7/25 08:49:00 da
0600: 6e 69 65 6c 6b 31 39 37 37 20 45 78 70 20 24 0a  nielk1977 Exp $.
0610: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
0620: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
0630: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0640: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0650: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0660: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0670: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0680: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0690: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
06a0: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
06b0: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
06c0: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
06d0: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06e0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06f0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
0700: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
0710: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
0720: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
0730: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0740: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75  ndif../*.** Ensu
0750: 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73  re these symbols
0760: 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65   were not define
0770: 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f  d by some previo
0780: 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a  us header file..
0790: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
07a0: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66  _VERSION.# undef
07b0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
07c0: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51  #endif.#ifdef SQ
07d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
07e0: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  BER.# undef SQLI
07f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0800: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  R.#endif../*.** 
0810: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
0820: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  e-Time Library V
0830: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b  ersion Numbers {
0840: 48 31 30 30 31 30 7d 20 3c 53 36 30 31 30 30 3e  H10010} <S60100>
0850: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
0860: 45 5f 56 45 52 53 49 4f 4e 20 61 6e 64 20 53 51  E_VERSION and SQ
0870: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
0880: 42 45 52 20 23 64 65 66 69 6e 65 73 20 69 6e 0a  BER #defines in.
0890: 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68  ** the sqlite3.h
08a0: 20 66 69 6c 65 20 73 70 65 63 69 66 79 20 74 68   file specify th
08b0: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  e version of SQL
08c0: 69 74 65 20 77 69 74 68 20 77 68 69 63 68 0a 2a  ite with which.*
08d0: 2a 20 74 68 61 74 20 68 65 61 64 65 72 20 66 69  * that header fi
08e0: 6c 65 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  le is associated
08f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 76 65 72  ..**.** The "ver
0900: 73 69 6f 6e 22 20 6f 66 20 53 51 4c 69 74 65 20  sion" of SQLite 
0910: 69 73 20 61 20 73 74 72 69 6e 67 20 6f 66 20 74  is a string of t
0920: 68 65 20 66 6f 72 6d 20 22 58 2e 59 2e 5a 22 2e  he form "X.Y.Z".
0930: 0a 2a 2a 20 54 68 65 20 70 68 72 61 73 65 20 22  .** The phrase "
0940: 61 6c 70 68 61 22 20 6f 72 20 22 62 65 74 61 22  alpha" or "beta"
0950: 20 6d 69 67 68 74 20 62 65 20 61 70 70 65 6e 64   might be append
0960: 65 64 20 61 66 74 65 72 20 74 68 65 20 5a 2e 0a  ed after the Z..
0970: 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 69  ** The X value i
0980: 73 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20  s major version 
0990: 6e 75 6d 62 65 72 20 61 6c 77 61 79 73 20 33 20  number always 3 
09a0: 69 6e 20 53 51 4c 69 74 65 33 2e 0a 2a 2a 20 54  in SQLite3..** T
09b0: 68 65 20 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20  he X value only 
09c0: 63 68 61 6e 67 65 73 20 77 68 65 6e 20 62 61 63  changes when bac
09d0: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
09e0: 6c 69 74 79 20 69 73 0a 2a 2a 20 62 72 6f 6b 65  lity is.** broke
09f0: 6e 20 61 6e 64 20 77 65 20 69 6e 74 65 6e 64 20  n and we intend 
0a00: 74 6f 20 6e 65 76 65 72 20 62 72 65 61 6b 20 62  to never break b
0a10: 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
0a20: 62 69 6c 69 74 79 2e 0a 2a 2a 20 54 68 65 20 59  bility..** The Y
0a30: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6d 69   value is the mi
0a40: 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  nor version numb
0a50: 65 72 20 61 6e 64 20 6f 6e 6c 79 20 63 68 61 6e  er and only chan
0a60: 67 65 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 72  ges when.** ther
0a70: 65 20 61 72 65 20 6d 61 6a 6f 72 20 66 65 61 74  e are major feat
0a80: 75 72 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73  ure enhancements
0a90: 20 74 68 61 74 20 61 72 65 20 66 6f 72 77 61 72   that are forwar
0aa0: 64 73 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a  ds compatible.**
0ab0: 20 62 75 74 20 6e 6f 74 20 62 61 63 6b 77 61 72   but not backwar
0ac0: 64 73 20 63 6f 6d 70 61 74 69 62 6c 65 2e 0a 2a  ds compatible..*
0ad0: 2a 20 54 68 65 20 5a 20 76 61 6c 75 65 20 69 73  * The Z value is
0ae0: 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d   the release num
0af0: 62 65 72 20 61 6e 64 20 69 73 20 69 6e 63 72 65  ber and is incre
0b00: 6d 65 6e 74 65 64 20 77 69 74 68 0a 2a 2a 20 65  mented with.** e
0b10: 61 63 68 20 72 65 6c 65 61 73 65 20 62 75 74 20  ach release but 
0b20: 72 65 73 65 74 73 20 62 61 63 6b 20 74 6f 20 30  resets back to 0
0b30: 20 77 68 65 6e 65 76 65 72 20 59 20 69 73 20 69   whenever Y is i
0b40: 6e 63 72 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a  ncremented..**.*
0b50: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0b60: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0b70: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
0b80: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0b90: 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  r()]..**.** INVA
0ba0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
0bb0: 31 30 30 31 31 7d 20 54 68 65 20 53 51 4c 49 54  10011} The SQLIT
0bc0: 45 5f 56 45 52 53 49 4f 4e 20 23 64 65 66 69 6e  E_VERSION #defin
0bd0: 65 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  e in the sqlite3
0be0: 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 20 73  .h header file s
0bf0: 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
0c00: 20 65 76 61 6c 75 61 74 65 20 74 6f 20 61 20 73   evaluate to a s
0c10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0c20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0c30: 20 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 20 20 20   version.**     
0c40: 20 20 20 20 20 77 69 74 68 20 77 68 69 63 68 20       with which 
0c50: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20  the header file 
0c60: 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a  is associated..*
0c70: 2a 0a 2a 2a 20 7b 48 31 30 30 31 34 7d 20 54 68  *.** {H10014} Th
0c80: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0c90: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 20  _NUMBER #define 
0ca0: 73 68 61 6c 6c 20 72 65 73 6f 6c 76 65 20 74 6f  shall resolve to
0cb0: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20   an integer.**  
0cc0: 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65          with the
0cd0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0ce0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0cf0: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d00: 5a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  Z.**          ar
0d10: 65 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73  e the major vers
0d20: 69 6f 6e 2c 20 6d 69 6e 6f 72 20 76 65 72 73 69  ion, minor versi
0d30: 6f 6e 2c 20 61 6e 64 20 72 65 6c 65 61 73 65 20  on, and release 
0d40: 6e 75 6d 62 65 72 2e 0a 2a 2f 0a 23 64 65 66 69  number..*/.#defi
0d50: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
0d60: 4e 20 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52  N         "--VER
0d70: 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c  S--".#define SQL
0d80: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d90: 45 52 20 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55  ER  --VERSION-NU
0da0: 4d 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41  MBER--../*.** CA
0db0: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
0dc0: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
0dd0: 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 32 30   Numbers {H10020
0de0: 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45  } <S60100>.** KE
0df0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
0e00: 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  version.**.** Th
0e10: 65 73 65 20 66 65 61 74 75 72 65 73 20 70 72 6f  ese features pro
0e20: 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e  vide the same in
0e30: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65  formation as the
0e40: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0e50: 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45  ].** and [SQLITE
0e60: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
0e70: 20 23 64 65 66 69 6e 65 73 20 69 6e 20 74 68 65   #defines in the
0e80: 20 68 65 61 64 65 72 2c 20 62 75 74 20 61 72 65   header, but are
0e90: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
0ea0: 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20  ith the library 
0eb0: 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68  instead of the h
0ec0: 65 61 64 65 72 20 66 69 6c 65 2e 20 20 43 61 75  eader file.  Cau
0ed0: 74 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d 65 72  tious programmer
0ee0: 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75  s might.** inclu
0ef0: 64 65 20 61 20 63 68 65 63 6b 20 69 6e 20 74 68  de a check in th
0f00: 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  eir application 
0f10: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 0a 2a  to verify that.*
0f20: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
0f30: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c  sion_number() al
0f40: 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
0f50: 20 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54   value.** [SQLIT
0f60: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0f70: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ]..**.** The sql
0f80: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f90: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
0fa0: 6e 73 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  ns the same info
0fb0: 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a  rmation as is.**
0fc0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
0fd0: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
0fe0: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
0ff0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76  function is prov
1000: 69 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20  ided.** for use 
1010: 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c  in DLLs since DL
1020: 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20  L users usually 
1030: 64 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 72 65  do not have dire
1040: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72  ct access to str
1050: 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73  ing.** constants
1060: 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e   within the DLL.
1070: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1080: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 31  S:.**.** {H10021
1090: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  } The [sqlite3_l
10a0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
10b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  ()] interface sh
10c0: 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  all return.**   
10d0: 20 20 20 20 20 20 20 61 6e 20 69 6e 74 65 67 65         an intege
10e0: 72 20 65 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49  r equal to [SQLI
10f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1100: 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32  R]..**.** {H1002
1110: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
1120: 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20  version] string 
1130: 63 6f 6e 73 74 61 6e 74 20 73 68 61 6c 6c 20 63  constant shall c
1140: 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20  ontain.**       
1150: 20 20 20 74 68 65 20 74 65 78 74 20 6f 66 20 74     the text of t
1160: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1170: 4f 4e 5d 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ON] string..**.*
1180: 2a 20 7b 48 31 30 30 32 33 7d 20 54 68 65 20 5b  * {H10023} The [
1190: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
11a0: 6f 6e 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73  on()] function s
11b0: 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20  hall return.**  
11c0: 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65          a pointe
11d0: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
11e0: 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e  3_version] strin
11f0: 67 20 63 6f 6e 73 74 61 6e 74 2e 0a 2a 2f 0a 53  g constant..*/.S
1200: 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e  QLITE_EXTERN con
1210: 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f  st char sqlite3_
1220: 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74  version[];.const
1230: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c   char *sqlite3_l
1240: 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b  ibversion(void);
1250: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62  .int sqlite3_lib
1260: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
1270: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
1280: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1290: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
12a0: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 20  y Is Threadsafe 
12b0: 7b 48 31 30 31 30 30 7d 20 3c 53 36 30 31 30 30  {H10100} <S60100
12c0: 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  >.**.** SQLite c
12d0: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77  an be compiled w
12e0: 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d  ith or without m
12f0: 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a  utexes.  When.**
1300: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1310: 45 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72  EADSAFE] C prepr
1320: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73  ocessor macro is
1330: 20 74 72 75 65 2c 20 6d 75 74 65 78 65 73 0a 2a   true, mutexes.*
1340: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1350: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1360: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1370: 61 74 20 6d 61 63 72 6f 20 69 73 20 66 61 6c 73  at macro is fals
1380: 65 2c 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  e,.** the mutexe
1390: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
13a0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
13b0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
13c0: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
13d0: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
13e0: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
13f0: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1400: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1410: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1420: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1430: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1440: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1450: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1460: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1470: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1480: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1490: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
14a0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
14b0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
14c0: 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  d..** The defaul
14d0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
14e0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
14f0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
1500: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
1510: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 20 70  n be used by a p
1520: 72 6f 67 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73  rogram to make s
1530: 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
1540: 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
1550: 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e  e that it is lin
1560: 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73  king against was
1570: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
1580: 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65  * the desired se
1590: 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51  tting of the [SQ
15a0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
15b0: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68   macro..**.** Th
15c0: 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c  is interface onl
15d0: 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65  y reports on the
15e0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75   compile-time mu
15f0: 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f  tex setting.** o
1600: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1610: 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20  READSAFE] flag. 
1620: 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
1630: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53  mpiled with.** S
1640: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1650: 3d 31 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =1 then mutexes 
1660: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
1670: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
1680: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
1690: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
16a0: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
16b0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
16c0: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
16d0: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
16e0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
16f0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
1700: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
1710: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
1720: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54  ONFIG_MUTEX].  T
1730: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1740: 6f 66 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  of this function
1750: 20 73 68 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74   shows.** only t
1760: 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6d 70 69  he default compi
1770: 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 2c  le-time setting,
1780: 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d   not any run-tim
1790: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
17a0: 74 68 61 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  that setting..**
17b0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
17c0: 2a 2a 0a 2a 2a 20 7b 48 31 30 31 30 31 7d 20 54  **.** {H10101} T
17d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  he [sqlite3_thre
17e0: 61 64 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69  adsafe()] functi
17f0: 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  on shall return 
1800: 6e 6f 6e 7a 65 72 6f 20 69 66 0a 2a 2a 20 20 20  nonzero if.**   
1810: 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 77 61         SQLite wa
1820: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1830: 74 68 65 20 69 74 73 20 6d 75 74 65 78 65 73 20  the its mutexes 
1840: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
1850: 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  lt.**          o
1860: 72 20 7a 65 72 6f 20 69 66 20 53 51 4c 69 74 65  r zero if SQLite
1870: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 73 75   was compiled su
1880: 63 68 20 74 68 61 74 20 6d 75 74 65 78 65 73 20  ch that mutexes 
1890: 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  are.**          
18a0: 70 65 72 6d 61 6e 65 6e 74 6c 79 20 64 69 73 61  permanently disa
18b0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  bled..**.** {H10
18c0: 31 30 32 7d 20 54 68 65 20 76 61 6c 75 65 20 72  102} The value r
18d0: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 5b  eturned by the [
18e0: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
18f0: 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  fe()] function.*
1900: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
1910: 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 65 6e   not change when
1920: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 20 61   mutex setting a
1930: 72 65 20 6d 6f 64 69 66 69 65 64 20 61 74 0a 2a  re modified at.*
1940: 2a 20 20 20 20 20 20 20 20 20 20 72 75 6e 74 69  *          runti
1950: 6d 65 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  me using the [sq
1960: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
1970: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 0a 2a  interface and .*
1980: 2a 20 20 20 20 20 20 20 20 20 20 65 73 70 65 63  *          espec
1990: 69 61 6c 6c 79 20 74 68 65 20 5b 53 51 4c 49 54  ially the [SQLIT
19a0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
19b0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 20 20 20 20 20  HREAD],.**      
19c0: 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46      [SQLITE_CONF
19d0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
19e0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
19f0: 53 45 52 49 41 4c 49 5a 45 44 5d 2c 0a 2a 2a 20  SERIALIZED],.** 
1a00: 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b 53 51           and [SQ
1a10: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
1a20: 58 5d 20 76 65 72 62 73 2e 0a 2a 2f 0a 69 6e 74  X] verbs..*/.int
1a30: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
1a40: 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  afe(void);../*.*
1a50: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
1a60: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
1a70: 48 61 6e 64 6c 65 20 7b 48 31 32 30 30 30 7d 20  Handle {H12000} 
1a80: 3c 53 34 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S40200>.** KEYW
1a90: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
1aa0: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
1ab0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ac0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
1ad0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
1ae0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
1af0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
1b00: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
1b10: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
1b20: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
1b30: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
1b40: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
1b50: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
1b60: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
1b70: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
1b80: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1b90: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1ba0: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
1bb0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
1bc0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
1bd0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
1be0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
1bf0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
1c00: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
1c10: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
1c20: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
1c30: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
1c40: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
1c50: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
1c60: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
1c70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
1c80: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
1c90: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
1ca0: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
1cb0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
1cc0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
1cd0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
1ce0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
1cf0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
1d00: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
1d10: 65 73 20 7b 48 31 30 32 30 30 7d 20 3c 53 31 30  es {H10200} <S10
1d20: 31 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  110>.** KEYWORDS
1d30: 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  : sqlite_int64 s
1d40: 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a  qlite_uint64.**.
1d50: 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65  ** Because there
1d60: 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61   is no cross-pla
1d70: 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65  tform way to spe
1d80: 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65  cify 64-bit inte
1d90: 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c  ger types.** SQL
1da0: 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70  ite includes typ
1db0: 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74  edefs for 64-bit
1dc0: 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69   signed and unsi
1dd0: 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a  gned integers..*
1de0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1df0: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
1e00: 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68  e3_uint64 are th
1e10: 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65  e preferred type
1e20: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a   definitions..**
1e30: 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36   The sqlite_int6
1e40: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
1e50: 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75  t64 types are su
1e60: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b  pported for back
1e70: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69  wards.** compati
1e80: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  bility only..**.
1e90: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1ea0: 2a 0a 2a 2a 20 7b 48 31 30 32 30 31 7d 20 54 68  *.** {H10201} Th
1eb0: 65 20 5b 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d  e [sqlite_int64]
1ec0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e   and [sqlite3_in
1ed0: 74 36 34 5d 20 74 79 70 65 20 73 68 61 6c 6c 20  t64] type shall 
1ee0: 73 70 65 63 69 66 79 0a 2a 2a 20 20 20 20 20 20  specify.**      
1ef0: 20 20 20 20 61 20 36 34 2d 62 69 74 20 73 69 67      a 64-bit sig
1f00: 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1f10: 2a 2a 20 7b 48 31 30 32 30 32 7d 20 54 68 65 20  ** {H10202} The 
1f20: 5b 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20  [sqlite_uint64] 
1f30: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e  and [sqlite3_uin
1f40: 74 36 34 5d 20 74 79 70 65 20 73 68 61 6c 6c 20  t64] type shall 
1f50: 73 70 65 63 69 66 79 0a 2a 2a 20 20 20 20 20 20  specify.**      
1f60: 20 20 20 20 61 20 36 34 2d 62 69 74 20 75 6e 73      a 64-bit uns
1f70: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a  igned integer..*
1f80: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
1f90: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
1fa0: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
1fb0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
1fc0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
1fd0: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
1fe0: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
1ff0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
2000: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2010: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2020: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2030: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2040: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2050: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2060: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2070: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2080: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2090: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
20a0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
20b0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
20c0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
20d0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
20e0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
20f0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2100: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2110: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2120: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2130: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2140: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2150: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2160: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2170: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2180: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2190: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
21a0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
21b0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
21c0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
21d0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
21e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
21f0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2200: 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 30  Connection {H120
2210: 31 30 7d 20 3c 53 33 30 31 30 30 3e 3c 53 34 30  10} <S30100><S40
2220: 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  200>.**.** This 
2230: 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64  routine is the d
2240: 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
2250: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2260: 63 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ct..**.** Applic
2270: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73  ations should [s
2280: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2290: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20  | finalize] all 
22a0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22b0: 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  ents].** and [sq
22c0: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
22d0: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
22e0: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73  LOB handles] ass
22f0: 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
2300: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2310: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
2320: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
2330: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a  e the object..**
2340: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65   The [sqlite3_ne
2350: 78 74 5f 73 74 6d 74 28 29 5d 20 69 6e 74 65 72  xt_stmt()] inter
2360: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
2370: 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a   to locate all.*
2380: 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2390: 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69 61 74  ements] associat
23a0: 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ed with a [datab
23b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
23c0: 69 66 20 64 65 73 69 72 65 64 2e 0a 2a 2a 20 54  if desired..** T
23d0: 79 70 69 63 61 6c 20 63 6f 64 65 20 6d 69 67 68  ypical code migh
23e0: 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73  t look like this
23f0: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2400: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c  ote><pre>.** sql
2410: 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2420: 3b 0a 2a 2a 20 77 68 69 6c 65 28 20 28 70 53 74  ;.** while( (pSt
2430: 6d 74 20 3d 20 73 71 6c 69 74 65 33 5f 6e 65 78  mt = sqlite3_nex
2440: 74 5f 73 74 6d 74 28 64 62 2c 20 30 29 29 21 3d  t_stmt(db, 0))!=
2450: 30 20 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  0 ){.** &nbsp;  
2460: 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2470: 65 28 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a  e(pStmt);.** }.*
2480: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
2490: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b  uote>.**.** If [
24a0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
24b0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c   is invoked whil
24c0: 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  e a transaction 
24d0: 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20  is open,.** the 
24e0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61  transaction is a
24f0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
2500: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
2510: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2520: 2a 20 7b 48 31 32 30 31 31 7d 20 41 20 73 75 63  * {H12011} A suc
2530: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2540: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2550: 29 5d 20 73 68 61 6c 6c 20 64 65 73 74 72 6f 79  )] shall destroy
2560: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2570: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2580: 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 20 43 2e  ction] object C.
2590: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 32 7d 20  .**.** {H12012} 
25a0: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
25b0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  l to [sqlite3_cl
25c0: 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c 20 72 65  ose(C)] shall re
25d0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  turn SQLITE_OK..
25e0: 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 33 7d 20 41  **.** {H12013} A
25f0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
2600: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
2610: 73 65 28 43 29 5d 20 73 68 61 6c 6c 20 72 65 6c  se(C)] shall rel
2620: 65 61 73 65 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  ease all.**     
2630: 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20       memory and 
2640: 73 79 73 74 65 6d 20 72 65 73 6f 75 72 63 65 73  system resources
2650: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2660: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2670: 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20  ction].**       
2680: 20 20 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32     C..**.** {H12
2690: 30 31 34 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b  014} A call to [
26a0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
26b0: 5d 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65  ] on a [database
26c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 20 74   connection] C t
26d0: 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
26e0: 68 61 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  has one or more 
26f0: 6f 70 65 6e 20 5b 70 72 65 70 61 72 65 64 20 73  open [prepared s
2700: 74 61 74 65 6d 65 6e 74 73 5d 20 73 68 61 6c 6c  tatements] shall
2710: 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20   fail with.**   
2720: 20 20 20 20 20 20 20 61 6e 20 5b 53 51 4c 49 54         an [SQLIT
2730: 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 63 6f  E_BUSY] error co
2740: 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31  de..**.** {H1201
2750: 35 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71  5} A call to [sq
2760: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
2770: 77 68 65 72 65 20 43 20 69 73 20 61 20 4e 55 4c  where C is a NUL
2780: 4c 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 0a  L pointer shall.
2790: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
27a0: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a  rn SQLITE_OK..**
27b0: 0a 2a 2a 20 7b 48 31 32 30 31 39 7d 20 57 68 65  .** {H12019} Whe
27c0: 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  n [sqlite3_close
27d0: 28 43 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20  (C)] is invoked 
27e0: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
27f0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 0a 2a 2a 20  onnection] C.** 
2800: 20 20 20 20 20 20 20 20 20 74 68 61 74 20 68 61           that ha
2810: 73 20 61 20 70 65 6e 64 69 6e 67 20 74 72 61 6e  s a pending tran
2820: 73 61 63 74 69 6f 6e 2c 20 74 68 65 20 74 72 61  saction, the tra
2830: 6e 73 61 63 74 69 6f 6e 20 73 68 61 6c 6c 20 62  nsaction shall b
2840: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f  e.**          ro
2850: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
2860: 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
2870: 0a 2a 2a 20 7b 41 31 32 30 31 36 7d 20 54 68 65  .** {A12016} The
2880: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
2890: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
28a0: 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  )] must be eithe
28b0: 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20  r a NULL.**     
28c0: 20 20 20 20 20 70 6f 69 6e 74 65 72 20 6f 72 20       pointer or 
28d0: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
28e0: 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61  ect pointer obta
28f0: 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ined.**         
2900: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f   from [sqlite3_o
2910: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
2920: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  _open16()], or.*
2930: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2940: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2950: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2960: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e  ly closed..*/.in
2970: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  t sqlite3_close(
2980: 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a  sqlite3 *);../*.
2990: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
29a0: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
29b0: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
29c0: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
29d0: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
29e0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
29f0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
2a00: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
2a10: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
2a20: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
2a30: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
2a40: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
2a50: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
2a60: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
2a70: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
2a80: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20  ution Interface 
2a90: 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30 30 30  {H12100} <S10000
2aa0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
2ab0: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2ac0: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2ad0: 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e 6e  ient way of runn
2ae0: 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  ing one or more.
2af0: 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
2b00: 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67  s without having
2b10: 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f 74 20   to write a lot 
2b20: 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65 20  of C code.  The 
2b30: 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a 2a  UTF-8 encoded.**
2b40: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
2b50: 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61 73  are passed in as
2b60: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
2b70: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2b80: 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65 20  _exec()..** The 
2b90: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
2ba0: 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79 20  valuated one by 
2bb0: 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 65 72  one until either
2bc0: 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a 20   an error or.** 
2bd0: 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73 20  an interrupt is 
2be0: 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72 20  encountered, or 
2bf0: 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20 61  until they are a
2c00: 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33 72  ll done.  The 3r
2c10: 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  d parameter.** i
2c20: 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63 61  s an optional ca
2c30: 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20 69  llback that is i
2c40: 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
2c50: 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79 20  each row of any 
2c60: 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74 73  query.** results
2c70: 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68 65   produced by the
2c80: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
2c90: 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65    The 5th parame
2ca0: 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65 0a  ter tells where.
2cb0: 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79 20  ** to write any 
2cc0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e 0a  error messages..
2cd0: 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72 20  **.** The error 
2ce0: 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 20 62  message passed b
2cf0: 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20  ack through the 
2d00: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  5th parameter is
2d10: 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f   held.** in memo
2d20: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
2d30: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2d40: 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20 61  ()].  To avoid a
2d50: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a   memory leak,.**
2d60: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 70 70   the calling app
2d70: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
2d80: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
2d90: 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72 72  ee()] on any err
2da0: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72 65  or.** message re
2db0: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
2dc0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2dd0: 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
2de0: 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74  ished using.** t
2df0: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
2e00: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
2e10: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
2e20: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2e30: 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  r is NULL or an 
2e40: 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a 20  empty string.** 
2e50: 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74  or a string cont
2e60: 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69 74  aining only whit
2e70: 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d 65  espace and comme
2e80: 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c  nts, then no SQL
2e90: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 61  .** statements a
2ea0: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
2eb0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
2ec0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a   not changed..**
2ed0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2ee0: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
2ef0: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
2f00: 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b  in terms of.** [
2f10: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2f20: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
2f30: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
2f40: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2f50: 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  ]..** The sqlite
2f60: 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e 65  3_exec() routine
2f70: 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f   does nothing to
2f80: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68   the database th
2f90: 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e  at cannot be don
2fa0: 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  e.** by [sqlite3
2fb0: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2fc0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2fd0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fe0: 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a  inalize()]..**.*
2ff0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
3000: 0a 2a 2a 20 7b 48 31 32 31 30 31 7d 20 41 20 73  .** {H12101} A s
3010: 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
3020: 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
3030: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3040: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ].**          sh
3050: 61 6c 6c 20 73 65 71 75 65 6e 74 69 61 6c 6c 79  all sequentially
3060: 20 65 76 61 6c 75 61 74 65 20 61 6c 6c 20 6f 66   evaluate all of
3070: 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
3080: 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed,.**          
3090: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
30a0: 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
30b0: 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
30c0: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20  erminated.**    
30d0: 20 20 20 20 20 20 73 74 72 69 6e 67 20 53 20 77        string S w
30e0: 69 74 68 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ithin the contex
30f0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
3100: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
3110: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 32 7d  ..**.** {H12102}
3120: 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d 65   If the S parame
3130: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3140: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d  exec(D,S,C,A,E)]
3150: 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a   is NULL then.**
3160: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 63            the ac
3170: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 69 6e 74  tions of the int
3180: 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62 65 20  erface shall be 
3190: 74 68 65 20 73 61 6d 65 20 61 73 20 69 66 20 74  the same as if t
31a0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  he.**          S
31b0: 20 70 61 72 61 6d 65 74 65 72 20 77 65 72 65 20   parameter were 
31c0: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
31d0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 34 7d 20  .**.** {H12104} 
31e0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
31f0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   of [sqlite3_exe
3200: 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 5b 53  c()] shall be [S
3210: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6c 6c  QLITE_OK] if all
3220: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
3230: 20 73 74 61 74 65 6d 65 6e 74 73 20 72 75 6e 20   statements run 
3240: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 6e 64  successfully and
3250: 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
3260: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 35 7d 20 54  **.** {H12105} T
3270: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
3280: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  of [sqlite3_exec
3290: 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 61 6e 20  ()] shall be an 
32a0: 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 20  appropriate.**  
32b0: 20 20 20 20 20 20 20 20 6e 6f 6e 2d 7a 65 72 6f          non-zero
32c0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
32d0: 20 61 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   any SQL stateme
32e0: 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  nt fails..**.** 
32f0: 7b 48 31 32 31 30 37 7d 20 49 66 20 6f 6e 65 20  {H12107} If one 
3300: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 53  or more of the S
3310: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 68 61  QL statements ha
3320: 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  nded to [sqlite3
3330: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20  _exec()].**     
3340: 20 20 20 20 20 72 65 74 75 72 6e 20 72 65 73 75       return resu
3350: 6c 74 73 20 61 6e 64 20 74 68 65 20 33 72 64 20  lts and the 3rd 
3360: 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 74  parameter is not
3370: 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a 2a 20 20   NULL, then.**  
3380: 20 20 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c          the call
3390: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 70  back function sp
33a0: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 33  ecified by the 3
33b0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 68 61  rd parameter sha
33c0: 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20  ll be.**        
33d0: 20 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66    invoked once f
33e0: 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 72  or each row of r
33f0: 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  esult..**.** {H1
3400: 32 31 31 30 7d 20 49 66 20 74 68 65 20 63 61 6c  2110} If the cal
3410: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20  lback returns a 
3420: 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 20 74  non-zero value t
3430: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  hen [sqlite3_exe
3440: 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  c()].**         
3450: 20 73 68 61 6c 6c 20 61 62 6f 72 74 20 74 68 65   shall abort the
3460: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
3470: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 65  t is currently e
3480: 76 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20 20 20  valuating,.**   
3490: 20 20 20 20 20 20 20 73 6b 69 70 20 61 6c 6c 20         skip all 
34a0: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
34b0: 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 72  tatements, and r
34c0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 41 42  eturn [SQLITE_AB
34d0: 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ORT]..**.** {H12
34e0: 31 31 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  113} The [sqlite
34f0: 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e  3_exec()] routin
3500: 65 20 73 68 61 6c 6c 20 70 61 73 73 20 69 74 73  e shall pass its
3510: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
3520: 68 72 6f 75 67 68 0a 2a 2a 20 20 20 20 20 20 20  hrough.**       
3530: 20 20 20 61 73 20 74 68 65 20 31 73 74 20 70 61     as the 1st pa
3540: 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 63  rameter of the c
3550: 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b  allback..**.** {
3560: 48 31 32 31 31 36 7d 20 54 68 65 20 5b 73 71 6c  H12116} The [sql
3570: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75  ite3_exec()] rou
3580: 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74  tine shall set t
3590: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
35a0: 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20   of its.**      
35b0: 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20      callback to 
35c0: 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
35d0: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
35e0: 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a 2a  current row of.*
35f0: 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
3600: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 39  t..**.** {H12119
3610: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
3620: 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73  xec()] routine s
3630: 68 61 6c 6c 20 73 65 74 20 74 68 65 20 33 72 64  hall set the 3rd
3640: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74   parameter of it
3650: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  s.**          ca
3660: 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20  llback to be an 
3670: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
3680: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c  s to strings hol
3690: 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ding the.**     
36a0: 20 20 20 20 20 76 61 6c 75 65 73 20 66 6f 72 20       values for 
36b0: 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74  each column in t
36c0: 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c  he current resul
36d0: 74 20 73 65 74 20 72 6f 77 20 61 73 0a 2a 2a 20  t set row as.** 
36e0: 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65           obtaine
36f0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
3700: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
3710: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 32 7d 20 54  **.** {H12122} T
3720: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
3730: 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c  ()] routine shal
3740: 6c 20 73 65 74 20 74 68 65 20 34 74 68 20 70 61  l set the 4th pa
3750: 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a  rameter of its.*
3760: 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
3770: 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72  ack to be an arr
3780: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3790: 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e  o strings holdin
37a0: 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  g the.**        
37b0: 20 20 6e 61 6d 65 73 20 6f 66 20 72 65 73 75 6c    names of resul
37c0: 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20 6f 62 74  t columns as obt
37d0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
37e0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
37f0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32  )]..**.** {H1212
3800: 35 7d 20 49 66 20 74 68 65 20 33 72 64 20 70 61  5} If the 3rd pa
3810: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
3820: 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 4e  te3_exec()] is N
3830: 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  ULL then.**     
3840: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78       [sqlite3_ex
3850: 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 69 6c 65  ec()] shall sile
3860: 6e 74 6c 79 20 64 69 73 63 61 72 64 20 71 75 65  ntly discard que
3870: 72 79 20 72 65 73 75 6c 74 73 2e 0a 2a 2a 0a 2a  ry results..**.*
3880: 2a 20 7b 48 31 32 31 33 31 7d 20 49 66 20 61 6e  * {H12131} If an
3890: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
38a0: 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72 20 65  ile parsing or e
38b0: 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20 6f 66  valuating any of
38c0: 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20 20   the SQL.**     
38d0: 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20       statements 
38e0: 69 6e 20 74 68 65 20 53 20 70 61 72 61 6d 65 74  in the S paramet
38f0: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  er of [sqlite3_e
3900: 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20  xec(D,S,C,A,E)] 
3910: 61 6e 64 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  and if.**       
3920: 20 20 20 74 68 65 20 45 20 70 61 72 61 6d 65 74     the E paramet
3930: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
3940: 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78  then [sqlite3_ex
3950: 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 74 6f 72  ec()] shall stor
3960: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
3970: 20 2a 45 20 61 6e 20 61 70 70 72 6f 70 72 69 61   *E an appropria
3980: 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
3990: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
39a0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  mory obtained.**
39b0: 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b            from [
39c0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
39d0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 34  ]..**.** {H12134
39e0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
39f0: 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20  xec(D,S,C,A,E)] 
3a00: 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65  routine shall se
3a10: 74 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  t the value of.*
3a20: 2a 20 20 20 20 20 20 20 20 20 20 2a 45 20 74 6f  *          *E to
3a30: 20 4e 55 4c 4c 20 69 66 20 45 20 69 73 20 6e 6f   NULL if E is no
3a40: 74 20 4e 55 4c 4c 20 61 6e 64 20 74 68 65 72 65  t NULL and there
3a50: 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a   are no errors..
3a60: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 37 7d 20 54  **.** {H12137} T
3a70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
3a80: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 66 75 6e  (D,S,C,A,E)] fun
3a90: 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20  ction shall set 
3aa0: 74 68 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  the [error code]
3ab0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
3ac0: 20 6d 65 73 73 61 67 65 20 61 63 63 65 73 73 69   message accessi
3ad0: 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ble via [sqlite3
3ae0: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
3af0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3b00: 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64  3_errmsg()], and
3b10: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3b20: 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  16()]..**.** {H1
3b30: 32 31 33 38 7d 20 49 66 20 74 68 65 20 53 20 70  2138} If the S p
3b40: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
3b50: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c  ite3_exec(D,S,C,
3b60: 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72  A,E)] is NULL or
3b70: 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
3b80: 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
3b90: 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67  contains nothing
3ba0: 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74   other than whit
3bb0: 65 73 70 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73  espace, comments
3bc0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  ,.**          an
3bd0: 64 2f 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c  d/or semicolons,
3be0: 20 74 68 65 6e 20 72 65 73 75 6c 74 73 20 6f 66   then results of
3bf0: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
3c00: 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  e()],.**        
3c10: 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73    [sqlite3_errms
3c20: 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  g()], and [sqlit
3c30: 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a  e3_errmsg16()].*
3c40: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
3c50: 20 72 65 73 65 74 20 74 6f 20 69 6e 64 69 63 61   reset to indica
3c60: 74 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a  te no errors..**
3c70: 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
3c80: 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 31 7d 20  .**.** {A12141} 
3c90: 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
3ca0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3cb0: 65 78 65 63 28 29 5d 20 6d 75 73 74 20 62 65 20  exec()] must be 
3cc0: 61 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65  an valid and ope
3cd0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  n.**          [d
3ce0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3cf0: 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31  on]..**.** {A121
3d00: 34 32 7d 20 54 68 65 20 64 61 74 61 62 61 73 65  42} The database
3d10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
3d20: 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20 77   not be closed w
3d30: 68 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  hile.**         
3d40: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3d50: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ] is running..**
3d60: 0a 2a 2a 20 7b 41 31 32 31 34 33 7d 20 54 68 65  .** {A12143} The
3d70: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
3d80: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71  n should use [sq
3d90: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f  lite3_free()] to
3da0: 20 66 72 65 65 0a 2a 2a 20 20 20 20 20 20 20 20   free.**        
3db0: 20 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61    the memory tha
3dc0: 74 20 2a 65 72 72 6d 73 67 20 69 73 20 6c 65 66  t *errmsg is lef
3dd0: 74 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 6f 6e  t pointing at on
3de0: 63 65 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ce the error.** 
3df0: 20 20 20 20 20 20 20 20 20 6d 65 73 73 61 67 65           message
3e00: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
3e10: 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  eded..**.** {A12
3e20: 31 34 35 7d 20 54 68 65 20 53 51 4c 20 73 74 61  145} The SQL sta
3e30: 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 20 74  tement text in t
3e40: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
3e50: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
3e60: 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  c()].**         
3e70: 20 6d 75 73 74 20 72 65 6d 61 69 6e 20 75 6e 63   must remain unc
3e80: 68 61 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 71  hanged while [sq
3e90: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
3ea0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
3eb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
3ec0: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
3ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ee0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
3ef0: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
3f00: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
3f10: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
3f20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3f30: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
3f40: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
3f50: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
3f60: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
3f70: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
3f80: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
3f90: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
3fa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fb0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
3fc0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
3fd0: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
3fe0: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
3ff0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4000: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
4010: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
4020: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
4030: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
4040: 43 6f 64 65 73 20 7b 48 31 30 32 31 30 7d 20 3c  Codes {H10210} <
4050: 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10700>.** KEYWO
4060: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
4070: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
4080: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4090: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
40a0: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
40b0: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
40c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
40d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
40e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
40f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4100: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4110: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73  r to indicates s
4120: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
4130: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
4140: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
4150: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
4160: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
4170: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
4180: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  so: [SQLITE_IOER
4190: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
41a0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a  d result codes].
41b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
41c0: 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30  E_OK           0
41d0: 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c     /* Successful
41e0: 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65   result */./* be
41f0: 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72  ginning-of-error
4200: 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e  -codes */.#defin
4210: 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20  e SQLITE_ERROR  
4220: 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c        1   /* SQL
4230: 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e   error or missin
4240: 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  g database */.#d
4250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4260: 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a  ERNAL     2   /*
4270: 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20   Internal logic 
4280: 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20  error in SQLite 
4290: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42a0: 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33  E_PERM         3
42b0: 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72     /* Access per
42c0: 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a  mission denied *
42d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
42e0: 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20  _ABORT        4 
42f0: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f    /* Callback ro
4300: 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20  utine requested 
4310: 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66  an abort */.#def
4320: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  ine SQLITE_BUSY 
4330: 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54          5   /* T
4340: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
4350: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
4360: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4370: 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a  KED       6   /*
4380: 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20   A table in the 
4390: 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b  database is lock
43a0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
43b0: 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20  LITE_NOMEM      
43c0: 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f    7   /* A mallo
43d0: 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64  c() failed */.#d
43e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
43f0: 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a  DONLY     8   /*
4400: 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74   Attempt to writ
4410: 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74  e a readonly dat
4420: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
4430: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50   SQLITE_INTERRUP
4440: 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72  T    9   /* Oper
4450: 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64  ation terminated
4460: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   by sqlite3_inte
4470: 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e  rrupt()*/.#defin
4480: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20  e SQLITE_IOERR  
4490: 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d       10   /* Som
44a0: 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49  e kind of disk I
44b0: 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65  /O error occurre
44c0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
44d0: 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20  ITE_CORRUPT     
44e0: 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  11   /* The data
44f0: 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20  base disk image 
4500: 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a  is malformed */.
4510: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4520: 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20  OTFOUND    12   
4530: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62  /* NOT USED. Tab
4540: 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74  le or record not
4550: 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e   found */.#defin
4560: 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20  e SQLITE_FULL   
4570: 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73       13   /* Ins
4580: 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65  ertion failed be
4590: 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69  cause database i
45a0: 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e  s full */.#defin
45b0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
45c0: 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61  N    14   /* Una
45d0: 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ble to open the 
45e0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
45f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4600: 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20  PROTOCOL    15  
4610: 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61   /* NOT USED. Da
4620: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4630: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4640: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4650: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4660: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4670: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
4680: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
4690: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
46a0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
46b0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
46c0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
46d0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
46e0: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
46f0: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4700: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4710: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4720: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4730: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4740: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4750: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4760: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4770: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
4780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4790: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
47a0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
47b0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
47c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
47d0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
47e0: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
47f0: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4800: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4820: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4830: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4840: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4850: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4860: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4870: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
4880: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
4890: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
48a0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
48b0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
48c0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
48d0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
48f0: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4900: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4910: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4920: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20  fine SQLITE_ROW 
4940: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
4950: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4960: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
4970: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
4980: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
4990: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
49a0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
49b0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
49c0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
49d0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
49e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
49f0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
4a00: 64 65 73 20 7b 48 31 30 32 32 30 7d 20 3c 53 31  des {H10220} <S1
4a10: 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0700>.** KEYWORD
4a20: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72  S: {extended err
4a30: 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64  or code} {extend
4a40: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a  ed error codes}.
4a50: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78  ** KEYWORDS: {ex
4a60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4a70: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65  de} {extended re
4a80: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
4a90: 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74  * In its default
4aa0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
4ab0: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69  SQLite API routi
4ac0: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  nes return one o
4ad0: 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20  f 26 integer.** 
4ae0: 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73  [SQLITE_OK | res
4af0: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
4b00: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
4b10: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20   has shown that 
4b20: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65  many of.** these
4b30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4b40: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61  e too coarse-gra
4b50: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
4b60: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
4b70: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
4b80: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
4b90: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
4ba0: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
4bb0: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
4bc0: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
4bd0: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
4be0: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
4bf0: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29  3.3.8 and later)
4c00: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70   include.** supp
4c10: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ort for addition
4c20: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  al result codes 
4c30: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72  that provide mor
4c40: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
4c50: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
4c60: 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65  errors. The exte
4c70: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4c80: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72  s are enabled or
4c90: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20   disabled.** on 
4ca0: 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63  a per database c
4cb0: 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20  onnection basis 
4cc0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
4cd0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
4ce0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41  esult_codes()] A
4cf0: 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f  PI..**.** Some o
4d00: 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  f the available 
4d10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4d20: 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64  codes are listed
4d30: 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61   here..** One ma
4d40: 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d  y expect the num
4d50: 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20  ber of extended 
4d60: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c  result codes wil
4d70: 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f  l be expand.** o
4d80: 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77  ver time.  Softw
4d90: 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78  are that uses ex
4da0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4db0: 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63  des should expec
4dc0: 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20  t.** to see new 
4dd0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20  result codes in 
4de0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
4df0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
4e00: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72   The SQLITE_OK r
4e10: 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20  esult code will 
4e20: 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65  never be extende
4e30: 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61  d.  It will alwa
4e40: 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79  ys.** be exactly
4e50: 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   zero..**.** INV
4e60: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
4e70: 48 31 30 32 32 33 7d 20 54 68 65 20 73 79 6d 62  H10223} The symb
4e80: 6f 6c 69 63 20 6e 61 6d 65 20 66 6f 72 20 61 6e  olic name for an
4e90: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4ea0: 20 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74   code shall cont
4eb0: 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ains.**         
4ec0: 20 61 20 72 65 6c 61 74 65 64 20 70 72 69 6d 61   a related prima
4ed0: 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61  ry result code a
4ee0: 73 20 61 20 70 72 65 66 69 78 2e 0a 2a 2a 0a 2a  s a prefix..**.*
4ef0: 2a 20 7b 48 31 30 32 32 34 7d 20 50 72 69 6d 61  * {H10224} Prima
4f00: 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e  ry result code n
4f10: 61 6d 65 73 20 73 68 61 6c 6c 20 63 6f 6e 74 61  ames shall conta
4f20: 69 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f 22 20  in a single "_" 
4f30: 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a  character..**.**
4f40: 20 7b 48 31 30 32 32 35 7d 20 45 78 74 65 6e 64   {H10225} Extend
4f50: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e  ed result code n
4f60: 61 6d 65 73 20 73 68 61 6c 6c 20 63 6f 6e 74 61  ames shall conta
4f70: 69 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22  in two or more "
4f80: 5f 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  _" characters..*
4f90: 2a 0a 2a 2a 20 7b 48 31 30 32 32 36 7d 20 54 68  *.** {H10226} Th
4fa0: 65 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  e numeric value 
4fb0: 6f 66 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72  of an extended r
4fc0: 65 73 75 6c 74 20 63 6f 64 65 20 73 68 61 6c 6c  esult code shall
4fd0: 20 63 6f 6e 74 61 69 6e 20 74 68 65 0a 2a 2a 20   contain the.** 
4fe0: 20 20 20 20 20 20 20 20 20 6e 75 6d 65 72 69 63           numeric
4ff0: 20 76 61 6c 75 65 20 6f 66 20 69 74 73 20 63 6f   value of its co
5000: 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 69 6d  rresponding prim
5010: 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ary result code 
5020: 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  in.**          i
5030: 74 73 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ts least signifi
5040: 63 61 6e 74 20 38 20 62 69 74 73 2e 0a 2a 2f 0a  cant 8 bits..*/.
5050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5060: 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20  OERR_READ       
5070: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5080: 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23  OERR | (1<<8)).#
5090: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50a0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20  ERR_SHORT_READ  
50b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50c0: 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ERR | (2<<8)).#d
50d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50e0: 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20  RR_WRITE        
50f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5100: 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  RR | (3<<8)).#de
5110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5120: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
5130: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5140: 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  R | (4<<8)).#def
5150: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5160: 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20  _DIR_FSYNC      
5170: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5180: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
5190: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
51a0: 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20  TRUNCATE        
51b0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51c0: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (6<<8)).#defin
51d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
51e0: 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20  STAT            
51f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5200: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
5210: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e   SQLITE_IOERR_UN
5220: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5230: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5240: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
5250: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c  SQLITE_IOERR_RDL
5260: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
5270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5280: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
5290: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
52a0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53  TE            (S
52b0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
52c0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
52d0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
52e0: 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53  KED           (S
52f0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5300: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5310: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45  QLITE_IOERR_NOME
5320: 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  M             (S
5330: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5340: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5350: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45  QLITE_IOERR_ACCE
5360: 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53  SS            (S
5370: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5380: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5390: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43  QLITE_IOERR_CHEC
53a0: 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53  KRESERVEDLOCK (S
53b0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
53c0: 34 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  4<<8))../*.** CA
53d0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
53e0: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
53f0: 61 74 69 6f 6e 73 20 7b 48 31 30 32 33 30 7d 20  ations {H10230} 
5400: 3c 48 31 31 31 32 30 3e 20 3c 48 31 32 37 30 30  <H11120> <H12700
5410: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  >.**.** These bi
5420: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5430: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5440: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5450: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5460: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5470: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5480: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5490: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78 4f  ameter to the xO
54a0: 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  pen method of th
54b0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
54c0: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
54d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
54e0: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20  N_READONLY      
54f0: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
5500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5510: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20  N_READWRITE     
5520: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5540: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20  N_CREATE        
5550: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
5560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5570: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20  N_DELETEONCLOSE 
5580: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
5590: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
55a0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  N_EXCLUSIVE     
55b0: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
55c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
55d0: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20  N_MAIN_DB       
55e0: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
55f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5600: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20  N_TEMP_DB       
5610: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
5620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5630: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20  N_TRANSIENT_DB  
5640: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64     0x00000400.#d
5650: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5660: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20  N_MAIN_JOURNAL  
5670: 20 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64     0x00000800.#d
5680: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5690: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20  N_TEMP_JOURNAL  
56a0: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
56b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
56c0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20  N_SUBJOURNAL    
56d0: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 64     0x00002000.#d
56e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
56f0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
5700: 20 20 20 30 78 30 30 30 30 34 30 30 30 0a 23 64     0x00004000.#d
5710: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5720: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20  N_NOMUTEX       
5730: 20 20 20 30 78 30 30 30 30 38 30 30 30 0a 0a 2f     0x00008000../
5740: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
5750: 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69  evice Characteri
5760: 73 74 69 63 73 20 7b 48 31 30 32 34 30 7d 20 3c  stics {H10240} <
5770: 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H11120>.**.** Th
5780: 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69 6c  e xDeviceCapabil
5790: 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20  ities method of 
57a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
57b0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
57c0: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
57d0: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
57e0: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74   vector of the t
57f0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
5800: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
5810: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
5820: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
5830: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
5840: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
5850: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
5860: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5870: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
5880: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
5890: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
58a0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
58b0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
58c0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
58d0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
58e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
58f0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
5900: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
5910: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
5920: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
5930: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
5940: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
5950: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
5960: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
5970: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
5980: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
5990: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
59a0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
59b0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
59c0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
59d0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
59e0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
59f0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
5a00: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
5a10: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
5a20: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
5a30: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
5a40: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5a50: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
5a60: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
5a70: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
5a80: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
5a90: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
5aa0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
5ab0: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
5ac0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5ad0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
5ae0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
5af0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5b00: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20  OCAP_ATOMIC512  
5b10: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
5b20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5b30: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
5b40: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
5b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5b60: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
5b70: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
5b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5b90: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
5ba0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
5bb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5bc0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
5bd0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
5be0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5bf0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
5c00: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
5c10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5c20: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
5c30: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
5c40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5c50: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
5c60: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a       0x00000100.
5c70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5c80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5c90: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
5ca0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5cb0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5cc0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
5cd0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5ce0: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
5cf0: 76 65 6c 73 20 7b 48 31 30 32 35 30 7d 20 3c 48  vels {H10250} <H
5d00: 31 31 31 32 30 3e 20 3c 48 31 31 33 31 30 3e 0a  11120> <H11310>.
5d10: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5d20: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5d30: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5d40: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5d50: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5d60: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5d70: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5d80: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5d90: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5da0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5db0: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5dc0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5dd0: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5de0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5df0: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5e00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5e10: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5e20: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5e30: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5e40: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5e50: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5e60: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5e70: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5e80: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5e90: 65 20 46 6c 61 67 73 20 7b 48 31 30 32 36 30 7d  e Flags {H10260}
5ea0: 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20   <H11120>.**.** 
5eb0: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
5ec0: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
5ed0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
5ee0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5ef0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
5f00: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
5f10: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
5f20: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
5f30: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
5f40: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
5f50: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
5f60: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
5f70: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
5f80: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
5f90: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
5fa0: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
5fb0: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
5fc0: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
5fd0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
5fe0: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
5ff0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
6000: 4e 4f 52 4d 41 4c 20 66 6c 61 67 20 6d 65 61 6e  NORMAL flag mean
6010: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d  s.** to use norm
6020: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
6030: 74 69 63 73 2e 20 54 68 65 20 53 51 4c 49 54 45  tics. The SQLITE
6040: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20  _SYNC_FULL flag 
6050: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
6060: 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66  Mac OS-X style f
6070: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
6080: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23  of fsync()..*/.#
6090: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
60a0: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
60b0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
60c0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
60d0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
60e0: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
60f0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6100: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
6110: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6120: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
6130: 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 31 31  File Handle {H11
6140: 31 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a  110} <S20110>.**
6150: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
6160: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
6170: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
6180: 66 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a  file in the OS.*
6190: 2a 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  * interface laye
61a0: 72 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  r.  Individual O
61b0: 53 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c  S interface impl
61c0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
61d0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
61e0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
61f0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
6200: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
6210: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
6220: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
6230: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
6240: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
6250: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6260: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
6270: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
6280: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
6290: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
62a0: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
62b0: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
62c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
62d0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
62e0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
62f0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
6300: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
6310: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
6320: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
6330: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
6340: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
6350: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
6360: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
6370: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
6380: 20 7b 48 31 31 31 32 30 7d 20 3c 53 32 30 31 31   {H11120} <S2011
6390: 30 3e 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  0>.**.** Every f
63a0: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
63b0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
63c0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70  xOpen method pop
63d0: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
63e0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
63f0: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
6400: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
6410: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
6420: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
6430: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
6440: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
6450: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
6460: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
6470: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
6480: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
6490: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
64a0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
64b0: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
64c0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
64d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
64e0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
64f0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
6500: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6510: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6520: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6530: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6540: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6550: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6560: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6570: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6580: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6590: 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS-X style fulls
65a0: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
65b0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
65c0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
65d0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
65e0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
65f0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
6600: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6610: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6620: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6630: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6640: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6650: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6660: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6670: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6680: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6690: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
66a0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
66b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
66c0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
66d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
66e0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
66f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6700: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6710: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6720: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6730: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6740: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6750: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6760: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6770: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6780: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6790: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
67a0: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
67b0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
67c0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
67d0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
67e0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
67f0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
6800: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6810: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6820: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6830: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6840: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6850: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6860: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6870: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6880: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6890: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
68a0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
68b0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
68c0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
68d0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
68e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
68f0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
6900: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6910: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6920: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6930: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6940: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6950: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6960: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6970: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6980: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6990: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
69a0: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
69b0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
69c0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
69d0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
69e0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
69f0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
6a00: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6a10: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6a20: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6a30: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6a40: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6a50: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6a60: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6a70: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6a80: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6a90: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6aa0: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
6ab0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
6ac0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
6ad0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
6ae0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
6af0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
6b00: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6b10: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6b20: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6b30: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6b40: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6b50: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6b60: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6b70: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6b80: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6b90: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6ba0: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6bb0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6bc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6bd0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6be0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6bf0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6c00: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6c10: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6c20: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6c30: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6c40: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6c50: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6c60: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6c70: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6c80: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6c90: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6ca0: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6cb0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6cc0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6cd0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6ce0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6cf0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6d00: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6d10: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6d20: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6d30: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6d40: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6d50: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6d60: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6d70: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6d80: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6d90: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6da0: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6db0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6dc0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6dd0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6de0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6df0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6e00: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6e10: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6e20: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6e30: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6e40: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6e50: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6e60: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6e70: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6e80: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6e90: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6ea0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6eb0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6ec0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6ed0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6ee0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6ef0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6f00: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6f10: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6f20: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6f30: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6f40: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6f50: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6f60: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6f70: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6f80: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6f90: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6fa0: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
6fb0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
6fc0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
6fd0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
6fe0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
6ff0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
7000: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
7010: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
7020: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
7030: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
7040: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
7050: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
7060: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
7070: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
7080: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
7090: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
70a0: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
70b0: 72 69 74 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  rite()..*/.typed
70c0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
70d0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
70e0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
70f0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
7100: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
7110: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
7120: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
7130: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7140: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
7150: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
7160: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
7170: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
7180: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
7190: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
71a0: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
71b0: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
71c0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
71d0: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
71e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
71f0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
7200: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
7210: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
7220: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
7230: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
7240: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7250: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
7260: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
7270: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
7280: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
7290: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
72a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
72b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
72c0: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
72d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
72e0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
72f0: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
7300: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7310: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
7320: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
7330: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
7340: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7350: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
7360: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
7370: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
7380: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
7390: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
73a0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
73b0: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
73c0: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
73d0: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
73e0: 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d  Opcodes {H11310}
73f0: 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30800>.**.** 
7400: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
7410: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
7420: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
7430: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
7440: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
7450: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7460: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
7470: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
7480: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
7490: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
74a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
74b0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
74c0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
74d0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
74e0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
74f0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
7500: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
7510: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
7520: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
7530: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
7540: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
7550: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7560: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
7570: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
7580: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7590: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
75a0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
75b0: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
75c0: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
75d0: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
75e0: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
75f0: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
7600: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
7610: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
7620: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
7630: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
7640: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
7650: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
7660: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
7670: 54 45 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a  TE        1../*.
7680: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
7690: 65 78 20 48 61 6e 64 6c 65 20 7b 48 31 37 31 31  ex Handle {H1711
76a0: 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a  0} <S20130>.**.*
76b0: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
76c0: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
76d0: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
76e0: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
76f0: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
7700: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
7710: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
7720: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
7730: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
7740: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
7750: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
7760: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
7770: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
7780: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
7790: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
77a0: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
77b0: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
77c0: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
77d0: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
77e0: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
77f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
7800: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
7810: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
7820: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7830: 65 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 34 30  e Object {H11140
7840: 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20100>.**.**
7850: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
7860: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
7870: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
7880: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
7890: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
78a0: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
78b0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
78c0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
78d0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
78e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
78f0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
7900: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
7910: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  stem"..**.** The
7920: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
7930: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
7940: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
7950: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
7960: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
7970: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
7980: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
7990: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
79a0: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
79b0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
79c0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
79d0: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
79e0: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
79f0: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
7a00: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
7a10: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
7a20: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
7a30: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
7a40: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
7a50: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
7a60: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
7a70: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
7a80: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
7a90: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
7aa0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
7ab0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
7ac0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
7ad0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
7ae0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
7af0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
7b00: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
7b10: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
7b20: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
7b30: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
7b40: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
7b50: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
7b60: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
7b70: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
7b80: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
7b90: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
7ba0: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
7bb0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
7bc0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
7bd0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
7be0: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
7bf0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
7c00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
7c10: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
7c20: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
7c30: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
7c40: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
7c50: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
7c60: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
7c70: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
7c80: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
7c90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
7ca0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
7cb0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
7cc0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
7cd0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
7ce0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
7cf0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
7d00: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
7d10: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
7d20: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
7d30: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
7d40: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
7d50: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
7d60: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
7d70: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
7d80: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
7d90: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
7da0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
7db0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
7dc0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
7dd0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
7de0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
7df0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
7e00: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
7e10: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
7e20: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
7e30: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34  es..**.** {H1114
7e40: 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  1} SQLite will g
7e50: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
7e60: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
7e70: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
7e80: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
7e90: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
7ea0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
7eb0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
7ec0: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
7ed0: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
7ee0: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
7ef0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
7f00: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
7f10: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
7f20: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 7b 45  is.** called. {E
7f30: 4e 44 7d 20 20 42 65 63 61 75 73 65 20 6f 66 20  ND}  Because of 
7f40: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
7f50: 74 65 6e 73 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tense,.** the [s
7f60: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
7f70: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
7f80: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
7f90: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
7fa0: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
7fb0: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
7fc0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
7fd0: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
7fe0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
7ff0: 73 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  s xOpen is a NUL
8000: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
8010: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
8020: 69 74 65 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ite its own temp
8030: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
8040: 68 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76  he file.  Whenev
8050: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
8060: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
8070: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
8080: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
8090: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
80a0: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
80b0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
80c0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
80d0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  OSE]..**.** {H11
80e0: 31 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61  142} The flags a
80f0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8100: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
8110: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
8120: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8130: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
8140: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8150: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8160: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
8170: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
8180: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
8190: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
81a0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
81b0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
81c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
81d0: 45 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20  E]. {END}.** If 
81e0: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
81f0: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
8200: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
8210: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
8220: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
8230: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
8240: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
8250: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
8260: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 33  t..**.** {H11143
8270: 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  } SQLite will al
8280: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
8290: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
82a0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
82b0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
82c0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
82d0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
82e0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
82f0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8300: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
8310: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8320: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
8330: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
8340: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
8350: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8360: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
8370: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8380: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
8390: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
83a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
83b0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
83c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
83d0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
83e0: 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  </ul> {END}.**.*
83f0: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
8400: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
8410: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
8420: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
8430: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
8440: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
8450: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
8460: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
8470: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
8480: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
8490: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
84a0: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
84b0: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
84c0: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
84d0: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
84e0: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
84f0: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
8500: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
8510: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
8520: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
8530: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
8540: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
8550: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
8560: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
8570: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
8580: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
8590: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
85a0: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
85b0: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
85c0: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
85d0: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
85e0: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
85f0: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
8600: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
8610: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
8620: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
8630: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
8640: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
8650: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
8660: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8670: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
8680: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
8690: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
86a0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34  ul>.**.** {H1114
86b0: 35 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  5} The [SQLITE_O
86c0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
86d0: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
86e0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
86f0: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
8700: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
8710: 7b 48 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51  {H11146} The [SQ
8720: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
8730: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
8740: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
8750: 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75    databases, jou
8760: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75  rnals and for su
8770: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
8780: 20 7b 48 31 31 31 34 37 7d 20 54 68 65 20 5b 53   {H11147} The [S
8790: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
87a0: 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  SIVE] flag means
87b0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
87c0: 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f   be opened.** fo
87d0: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
87e0: 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69  ss.  This flag i
87f0: 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69  s set for all fi
8800: 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f  les except.** fo
8810: 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  r the main datab
8820: 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  ase file..**.** 
8830: 7b 48 31 31 31 34 38 7d 20 41 74 20 6c 65 61 73  {H11148} At leas
8840: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
8850: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
8860: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
8870: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
8880: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
8890: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
88a0: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
88b0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
88c0: 4f 70 65 6e 2e 20 7b 45 4e 44 7d 20 20 54 68 65  Open. {END}  The
88d0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
88e0: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
88f0: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
8900: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
8910: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
8920: 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31   in..**.** {H111
8930: 34 39 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72  49} The flags ar
8940: 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73  gument to xAcces
8950: 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49  s() may be [SQLI
8960: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
8970: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72  ].** to test for
8980: 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f   the existence o
8990: 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51  f a file, or [SQ
89a0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
89b0: 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73  WRITE] to.** tes
89c0: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
89d0: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
89e0: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
89f0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
8a00: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68  D].** to test wh
8a10: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
8a20: 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c  at least readabl
8a30: 65 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 66 69  e. {END}  The fi
8a40: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
8a50: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
8a60: 7b 48 31 31 31 35 30 7d 20 53 51 4c 69 74 65 20  {H11150} SQLite 
8a70: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
8a80: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
8a90: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
8aa0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
8ab0: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
8ac0: 61 74 68 6e 61 6d 65 2e 20 7b 48 31 31 31 35 31  athname. {H11151
8ad0: 7d 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65  } The exact size
8ae0: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
8af0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
8b00: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
8b10: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
8b20: 6d 65 74 68 6f 64 73 2e 20 7b 45 4e 44 7d 20 20  methods. {END}  
8b30: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
8b40: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
8b50: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
8b60: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
8b70: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
8b80: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
8b90: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
8ba0: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
8bb0: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
8bc0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
8bd0: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
8be0: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
8bf0: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
8c00: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
8c10: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
8c20: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
8c30: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
8c40: 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72  eep(), and xCurr
8c50: 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66  entTime() interf
8c60: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
8c70: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
8c80: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
8c90: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
8ca0: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
8cb0: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
8cc0: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
8cd0: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
8ce0: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
8cf0: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
8d00: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
8d10: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
8d20: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
8d30: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
8d40: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
8d50: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
8d60: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
8d70: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
8d80: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
8d90: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
8da0: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
8db0: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
8dc0: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
8dd0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
8de0: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
8df0: 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69    The xCurrentTi
8e00: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
8e10: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
8e20: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
8e30: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
8e40: 61 6e 64 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70  and time..*/.typ
8e50: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
8e60: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
8e70: 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  vfs;.struct sqli
8e80: 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20  te3_vfs {.  int 
8e90: 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20  iVersion;       
8ea0: 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72       /* Structur
8eb0: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
8ec0: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
8ed0: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
8ee0: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
8ef0: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
8f00: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
8f10: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
8f20: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
8f30: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
8f40: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
8f50: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
8f60: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
8f70: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
8f80: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
8f90: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
8fa0: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
8fb0: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
8fc0: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
8fd0: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
8fe0: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
8ff0: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
9000: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
9010: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
9020: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
9030: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
9040: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
9050: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
9060: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
9070: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
9080: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
9090: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
90a0: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
90b0: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
90c0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
90d0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
90e0: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
90f0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
9100: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
9110: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
9120: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
9130: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
9140: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
9150: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
9160: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9170: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
9180: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
9190: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
91a0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
91b0: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
91c0: 20 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69   *(*xDlSym)(sqli
91d0: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
91e0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
91f0: 62 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  bol);.  void (*x
9200: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
9210: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
9220: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
9230: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
9240: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
9250: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
9260: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
9270: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
9280: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
9290: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
92a0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
92b0: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
92c0: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
92d0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
92e0: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
92f0: 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20   New fields may 
9300: 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66  be appended in f
9310: 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20  igure versions. 
9320: 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20   The iVersion.  
9330: 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e  ** value will in
9340: 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72  crement whenever
9350: 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a   this happens. *
9360: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
9370: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
9380: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
9390: 6d 65 74 68 6f 64 20 7b 48 31 31 31 39 30 7d 20  method {H11190} 
93a0: 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 7b  <H11140>.**.** {
93b0: 48 31 31 31 39 31 7d 20 54 68 65 73 65 20 69 6e  H11191} These in
93c0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
93d0: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
93e0: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
93f0: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
9400: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
9410: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
9420: 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54  object. {END}  T
9430: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
9440: 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65   what kind of pe
9450: 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41  rmissions the xA
9460: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20  ccess method is 
9470: 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20  looking for..** 
9480: 7b 48 31 31 31 39 32 7d 20 57 69 74 68 20 53 51  {H11192} With SQ
9490: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
94a0: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
94b0: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
94c0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
94d0: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
94e0: 0a 2a 2a 20 7b 48 31 31 31 39 33 7d 20 57 69 74  .** {H11193} Wit
94f0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
9500: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
9510: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
9520: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
9530: 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68  the file is both
9540: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
9550: 69 74 61 62 6c 65 2e 0a 2a 2a 20 7b 48 31 31 31  itable..** {H111
9560: 39 34 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f  94} With SQLITE_
9570: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
9580: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
9590: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
95a0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
95b0: 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69  adable..*/.#defi
95c0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
95d0: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
95e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
95f0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23  SS_READWRITE 1.#
9600: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
9610: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
9620: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9630: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
9640: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20   SQLite Library 
9650: 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30  {H10130} <S20000
9660: 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S30100>.**.** 
9670: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9680: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9690: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
96a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
96b0: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
96c0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
96d0: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
96e0: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
96f0: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
9700: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
9710: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
9720: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
9730: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9740: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
9750: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
9760: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
9770: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
9780: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
9790: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
97a0: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
97b0: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
97c0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
97d0: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
97e0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
97f0: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
9800: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
9810: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9820: 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63  .  Only an effec
9830: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
9840: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9850: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
9860: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
9870: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
9880: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
9890: 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  o-ops..**.** Amo
98a0: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
98b0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
98c0: 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f  ize() shall invo
98d0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
98e0: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
98f0: 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75  rly, sqlite3_shu
9900: 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c  tdown().** shall
9910: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
9920: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
9930: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9940: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9950: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
9960: 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  OK on success..*
9970: 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65  * If for some re
9980: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
9990: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
99a0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
99b0: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
99c0: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
99d0: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
99e0: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
99f0: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
9a00: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
9a10: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
9a20: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
9a30: 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a  SQLITE_OK..**.**
9a40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
9a50: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
9a60: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
9a70: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
9a80: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
9a90: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
9aa0: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
9ab0: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
9ac0: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
9ad0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
9ae0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
9af0: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
9b00: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
9b10: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
9b20: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9b30: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
9b40: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
9b50: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
9b60: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
9b70: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
9b80: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
9b90: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
9ba0: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
9bb0: 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66  dy.  However, if
9bc0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
9bd0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
9be0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
9bf0: 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  T.** compile-tim
9c00: 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
9c10: 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
9c20: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
9c30: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
9c40: 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
9c50: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
9c60: 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
9c70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
9c80: 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
9c90: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
9ca0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
9cb0: 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
9cc0: 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
9cd0: 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
9ce0: 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
9cf0: 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
9d00: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
9d10: 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
9d20: 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
9d30: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
9d40: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
9d50: 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
9d60: 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
9d70: 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
9d80: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
9d90: 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
9da0: 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
9db0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
9dc0: 64 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4f 4d  d with SQLITE_OM
9dd0: 49 54 5f 41 55 54 4f 49 4e 49 54 20 6d 69 67 68  IT_AUTOINIT migh
9de0: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
9df0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
9e00: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
9e10: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
9e20: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
9e30: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
9e40: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
9e50: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
9e60: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
9e70: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
9e80: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
9e90: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
9ea0: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
9eb0: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
9ec0: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
9ed0: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
9ee0: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
9ef0: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
9f00: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
9f10: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
9f20: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
9f30: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
9f40: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
9f50: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
9f60: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
9f70: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
9f80: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
9f90: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
9fa0: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
9fb0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
9fc0: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
9fd0: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
9fe0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
9ff0: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
a000: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
a010: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
a020: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
a030: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
a040: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
a050: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
a060: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a070: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
a080: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
a090: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
a0a0: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
a0b0: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
a0c0: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
a0d0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a0e0: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
a0f0: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
a100: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
a110: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
a120: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
a130: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
a140: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a150: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
a160: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
a170: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
a180: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
a190: 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e  ed for unix, win
a1a0: 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a  dows, or os/2..*
a1b0: 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f 72  * When built for
a1c0: 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
a1d0: 20 28 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49   (using the SQLI
a1e0: 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 20 63 6f  TE_OS_OTHER=1 co
a1f0: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
a200: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
a210: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
a220: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
a230: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
a240: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
a250: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
a260: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
a270: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
a280: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
a290: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
a2a0: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
a2b0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
a2c0: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53 51  * must return SQ
a2d0: 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65  LITE_OK on succe
a2e0: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
a2f0: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
a300: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
a310: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
a320: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
a330: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
a340: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
a350: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
a360: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
a370: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
a380: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
a390: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
a3a0: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
a3b0: 79 20 7b 48 31 30 31 34 35 7d 20 3c 53 32 30 30  y {H10145} <S200
a3c0: 30 30 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a 0a 2a  00><S30200>.**.*
a3d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
a3e0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
a3f0: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
a400: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
a410: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
a420: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
a430: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
a440: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
a450: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
a460: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
a470: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
a480: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
a490: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
a4a0: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
a4b0: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
a4c0: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
a4d0: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
a4e0: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
a4f0: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
a500: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
a510: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
a520: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
a530: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
a540: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
a550: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
a560: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
a570: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
a580: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
a590: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
a5a0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
a5b0: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
a5c0: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
a5d0: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
a5e0: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
a5f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
a600: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
a610: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
a620: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
a630: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
a640: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
a650: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
a660: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
a670: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
a680: 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
a690: 72 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  r, that sqlite3_
a6a0: 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
a6b0: 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
a6c0: 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
a6d0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
a6e0: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
a6f0: 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
a700: 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
a710: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
a720: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
a730: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
a740: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r.** [SQLITE_CON
a750: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
a760: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
a770: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
a780: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
a790: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
a7a0: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
a7b0: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
a7c0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
a7d0: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
a7e0: 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   on the [SQLITE_
a7f0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
a800: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  EAD | configurat
a810: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
a820: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
a830: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
a840: 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
a850: 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
a860: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a870: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
a880: 4f 4b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  OK..** If the op
a890: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
a8a0: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
a8b0: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
a8c0: 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
a8d0: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
a8e0: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
a8f0: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
a900: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
a910: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
a920: 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
a930: 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 20 74  xperimental in t
a940: 68 61 74 0a 2a 2a 20 6e 65 77 20 63 6f 6e 66 69  hat.** new confi
a950: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
a960: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
a970: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
a980: 20 61 6e 64 20 65 78 69 73 74 69 6e 67 0a 2a 2a   and existing.**
a990: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
a9a0: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 64 69  ptions may be di
a9b0: 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 6d 6f  scontinued or mo
a9c0: 64 69 66 69 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  dified..*/.int s
a9d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
a9e0: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
a9f0: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
aa00: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
aa10: 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 3c 53  ines {H10155} <S
aa20: 32 30 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20  20120>.**.** An 
aa30: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
aa40: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
aa50: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
aa60: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
aa70: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
aa80: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
aa90: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
aaa0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
aab0: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
aac0: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
aad0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
aae0: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
aaf0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
ab00: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
ab10: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
ab20: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ab30: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
ab40: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ab50: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
ab60: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
ab70: 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
ab80: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
ab90: 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
aba0: 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
abb0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 64  ite3_config()] d
abc0: 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  uring configurat
abd0: 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c 69  ion, an.** appli
abe0: 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
abf0: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
ac00: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
ac10: 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a  ion subsystem.**
ac20: 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
ac30: 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
ac40: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
ac50: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   needs..**.** No
ac60: 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  te that SQLite c
ac70: 6f 6d 65 73 20 77 69 74 68 20 61 20 62 75 69 6c  omes with a buil
ac80: 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
ac90: 63 61 74 6f 72 20 74 68 61 74 20 69 73 0a 2a 2a  cator that is.**
aca0: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
acb0: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
acc0: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
acd0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
ace0: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
acf0: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
ad00: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
ad10: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
ad20: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
ad30: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
ad40: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ad50: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
ad60: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
ad70: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
ad80: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
ad90: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
ada0: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
adb0: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
adc0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
add0: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
ade0: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
adf0: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
ae00: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
ae10: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
ae20: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
ae30: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
ae40: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
ae50: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 46   The xMalloc, xF
ae60: 72 65 65 2c 20 61 6e 64 20 78 52 65 61 6c 6c 6f  ree, and xReallo
ae70: 63 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  c methods must w
ae80: 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
ae90: 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65 65 28 29  malloc(), free()
aea0: 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63 28 29 20  , and realloc() 
aeb0: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
aec0: 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72  he standard libr
aed0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  ary..**.** xSize
aee0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
aef0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
af00: 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
af10: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
af20: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
af30: 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
af40: 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
af50: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
af60: 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
af70: 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
af80: 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
af90: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
afa0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
afb0: 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
afc0: 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
afd0: 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
afe0: 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
aff0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b000: 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
b010: 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
b020: 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
b030: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
b040: 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
b050: 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
b060: 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
b070: 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
b080: 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
b090: 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
b0a0: 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
b0b0: 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
b0c0: 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  f 2..**.** The x
b0d0: 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
b0e0: 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
b0f0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28  ry allocator.  (
b100: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
b110: 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
b120: 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
b130: 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
b140: 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
b150: 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
b160: 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
b170: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
b180: 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
b190: 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
b1a0: 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
b1b0: 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
b1c0: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
b1d0: 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
b1e0: 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
b1f0: 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
b200: 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
b210: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
b220: 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
b230: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
b240: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
b250: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
b260: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
b270: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
b280: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
b290: 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
b2a0: 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
b2b0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b2c0: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
b2d0: 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
b2e0: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
b2f0: 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
b300: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
b310: 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
b320: 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
b330: 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
b340: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
b350: 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
b360: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
b370: 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
b380: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
b390: 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
b3a0: 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
b3b0: 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
b3c0: 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
b3d0: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
b3e0: 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
b3f0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
b400: 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
b410: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
b420: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
b430: 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
b440: 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
b450: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
b460: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
b470: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
b480: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
b490: 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
b4a0: 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
b4b0: 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
b4c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
b4d0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
b4e0: 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d 20 3c 53  ions {H10160} <S
b4f0: 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20000>.**.** The
b500: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
b510: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
b520: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
b530: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
b540: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
b550: 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
b560: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
b570: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
b580: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
b590: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
b5a0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
b5b0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
b5c0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
b5d0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
b5e0: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
b5f0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
b600: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
b610: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
b620: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
b630: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
b640: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
b650: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
b660: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
b670: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
b680: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
b690: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
b6a0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
b6b0: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
b6c0: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
b6d0: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
b6e0: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
b6f0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
b700: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
b710: 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
b720: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
b730: 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
b740: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
b750: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
b760: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
b770: 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65  s option disable
b780: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
b790: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
b7a0: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
b7b0: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
b7c0: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
b7d0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f  single thread.</
b7e0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
b7f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
b800: 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
b810: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
b820: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
b830: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73  is option.  This
b840: 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73   option disables
b850: 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
b860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
b870: 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
b880: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
b890: 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
b8a0: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
b8b0: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
b8c0: 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
b8d0: 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
b8e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
b8f0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
b900: 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
b910: 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
b920: 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
b930: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
b940: 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
b950: 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
b960: 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
b970: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
b980: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
b990: 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
b9a0: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
b9b0: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
b9c0: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68  this option.  Th
b9d0: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
b9e0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
b9f0: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
ba00: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
ba10: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
ba20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
ba30: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
ba40: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
ba50: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
ba60: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
ba70: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
ba80: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
ba90: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
baa0: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
bab0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
bac0: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
bad0: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
bae0: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
baf0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
bb00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
bb10: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
bb20: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
bb30: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
bb40: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
bb50: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
bb60: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
bb70: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
bb80: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
bb90: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
bba0: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 70 3e   time..**.** <p>
bbb0: 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
bbc0: 6f 6e 20 6f 70 74 69 6f 6e 20 6d 65 72 65 6c 79  on option merely
bbd0: 20 73 65 74 73 20 74 68 65 20 64 65 66 61 75 6c   sets the defaul
bbe0: 74 20 6d 75 74 65 78 20 0a 2a 2a 20 62 65 68 61  t mutex .** beha
bbf0: 76 69 6f 72 20 74 6f 20 73 65 72 69 61 6c 69 7a  vior to serializ
bc00: 65 20 61 63 63 65 73 73 20 74 6f 20 5b 64 61 74  e access to [dat
bc10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bc20: 73 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 0a  s].  Individual.
bc30: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
bc40: 6e 65 63 74 69 6f 6e 73 5d 20 63 61 6e 20 6f 76  nections] can ov
bc50: 65 72 72 69 64 65 20 74 68 69 73 20 73 65 74 74  erride this sett
bc60: 69 6e 67 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  ing.** using the
bc70: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
bc80: 4d 55 54 45 58 5d 20 66 6c 61 67 20 74 6f 20 5b  MUTEX] flag to [
bc90: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
bca0: 29 5d 2e 3c 2f 70 3e 3c 2f 64 64 3e 0a 2a 2a 0a  )].</p></dd>.**.
bcb0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
bcc0: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
bcd0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
bce0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
bcf0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
bd00: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
bd10: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
bd20: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
bd30: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
bd40: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
bd50: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
bd60: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
bd70: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
bd80: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
bd90: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
bda0: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
bdb0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
bdc0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
bdd0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
bde0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bdf0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
be00: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
be10: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
be20: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
be30: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
be40: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
be50: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
be60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
be70: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
be80: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
be90: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
bea0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
beb0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
bec0: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
bed0: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
bee0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
bef0: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
bf00: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
bf10: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
bf20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
bf30: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
bf40: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
bf50: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
bf60: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
bf70: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
bf80: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
bf90: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
bfa0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bfb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
bfc0: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
bfd0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
bfe0: 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 62 6f 6f  takes single boo
bff0: 6c 65 61 6e 20 61 72 67 75 6d 65 6e 74 20 77 68  lean argument wh
c000: 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
c010: 69 73 61 62 6c 65 73 0a 2a 2a 20 74 68 65 20 63  isables.** the c
c020: 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
c030: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
c040: 74 61 74 69 73 74 69 63 73 2e 20 20 57 68 65 6e  tatistics.  When
c050: 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 0a 2a   disabled, the.*
c060: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  * following SQLi
c070: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
c080: 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
c090: 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
c0a0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
c0b0: 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
c0c0: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
c0d0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
c0e0: 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
c0f0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
c100: 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a  _heap_limit()].*
c110: 2a 20 20 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33  *   <li> sqlite3
c120: 5f 6d 65 6d 6f 72 79 5f 73 74 61 74 75 73 28 29  _memory_status()
c130: 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c  .**   </ul>.** <
c140: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
c150: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
c160: 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
c170: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  >This option spe
c180: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
c190: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
c1a0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
c1b0: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
c1c0: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
c1d0: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
c1e0: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
c1f0: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74  to the memory, t
c200: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
c210: 63 68 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ch scratch buffe
c220: 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
c230: 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72  number of buffer
c240: 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
c250: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
c260: 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
c270: 20 31 36 2e 20 54 68 65 20 66 69 72 73 74 0a 2a   16. The first.*
c280: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
c290: 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
c2a0: 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
c2b0: 65 61 73 74 20 28 73 7a 2b 34 29 2a 4e 20 62 79  east (sz+4)*N by
c2c0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
c2d0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  * SQLite will us
c2e0: 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e no more than o
c2f0: 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ne scratch buffe
c300: 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68  r at once per th
c310: 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68  read, so.** N sh
c320: 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
c330: 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
c340: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
c350: 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a  reads.  The sz.*
c360: 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  * parameter shou
c370: 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 74 68  ld be 6 times th
c380: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
c390: 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
c3a0: 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72  age size..** Scr
c3b0: 61 74 63 68 20 62 75 66 66 65 72 73 20 61 72 65  atch buffers are
c3c0: 20 75 73 65 64 20 61 73 20 70 61 72 74 20 6f 66   used as part of
c3d0: 20 74 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e   the btree balan
c3e0: 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49  ce operation.  I
c3f0: 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62  f.** The btree b
c400: 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64  alancer needs ad
c410: 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20  ditional memory 
c420: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
c430: 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63  rovided by.** sc
c440: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 6f 72  ratch buffers or
c450: 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62   if no scratch b
c460: 75 66 66 65 72 20 73 70 61 63 65 20 69 73 20 73  uffer space is s
c470: 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53  pecified, then S
c480: 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f  QLite.** goes to
c490: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
c4a0: 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  ()] to obtain th
c4b0: 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64  e memory it need
c4c0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
c4d0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c4e0: 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
c4f0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
c500: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
c510: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
c520: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
c530: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
c540: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
c550: 63 61 63 68 65 2e 20 20 54 68 65 72 65 20 61 72  cache.  There ar
c560: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
c570: 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: A pointer to 
c580: 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  the.** memory, t
c590: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
c5a0: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
c5b0: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
c5c0: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
c5d0: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
c5e0: 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 77 65  t must be a powe
c5f0: 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
c600: 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 2e 20   512 and 32768. 
c610: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
c620: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
c630: 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
c640: 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
c650: 20 28 73 7a 2b 34 29 2a 4e 20 62 79 74 65 73 20   (sz+4)*N bytes 
c660: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51  of memory..** SQ
c670: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
c680: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
c690: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
c6a0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
c6b0: 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
c6c0: 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
c6d0: 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
c6e0: 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
c6f0: 68 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e  he.  If addition
c700: 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
c710: 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
c720: 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
c730: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
c740: 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
c750: 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
c760: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
c770: 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
c780: 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
c790: 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  pace.</dd>.**.**
c7a0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
c7b0: 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
c7c0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
c7d0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
c7e0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
c7f0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
c800: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
c810: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
c820: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c830: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
c840: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
c850: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
c860: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
c870: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
c880: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
c890: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
c8a0: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70  e arguments: A p
c8b0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
c8c0: 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72  mory, the number
c8d0: 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
c8e0: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
c8f0: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
c900: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
c910: 7a 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 66  ze.  If.** the f
c920: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
c930: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
c940: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
c950: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
c960: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
c970: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
c980: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
c990: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
c9a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
c9b0: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
c9c0: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
c9d0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
c9e0: 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65  MALLOC].  If the
c9f0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
ca00: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  er is not NULL a
ca10: 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  nd either [SQLIT
ca20: 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
ca30: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
ca40: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
ca50: 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65  are defined, the
ca60: 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
ca70: 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
ca80: 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
ca90: 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
caa0: 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
cab0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
cac0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
cad0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
cae0: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
caf0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
cb00: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
cb10: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
cb20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
cb30: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
cb40: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
cb50: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
cb60: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
cb70: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
cb80: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
cb90: 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
cba0: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
cbb0: 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20  in place.** the 
cbc0: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
cbd0: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
cbe0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
cbf0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
cc00: 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
cc10: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
cc20: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
cc30: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
cc40: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
cc50: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
cc60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
cc70: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
cc80: 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
cc90: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
cca0: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
ccb0: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
ccc0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
ccd0: 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
cce0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73  outines..** This
ccf0: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
cd00: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
cd10: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
cd20: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
cd30: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
cd40: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
cd50: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
cd60: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
cd70: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
cd80: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
cd90: 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2f 0a  xample.</dd>.*/.
cda0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
cdb0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
cdc0: 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
cdd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cde0: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
cdf0: 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
ce00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ce10: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
ce20: 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
ce30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ce40: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
ce50: 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
ce60: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
ce70: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
ce80: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
ce90: 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
cea0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
ceb0: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
cec0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
ced0: 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
cee0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
cef0: 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
cf00: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
cf10: 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
cf20: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
cf30: 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
cf40: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
cf50: 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
cf60: 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
cf70: 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
cf80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
cf90: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
cfa0: 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
cfb0: 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
cfc0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
cfd0: 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
cfe0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
cff0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
d000: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
d010: 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
d020: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
d030: 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
d040: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
d050: 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
d060: 20 20 31 32 20 20 2f 2a 20 69 6e 74 20 74 68 72    12  /* int thr
d070: 65 73 68 6f 6c 64 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  eshold */.../*.*
d080: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
d090: 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
d0a0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
d0b0: 64 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53 31  des {H12200} <S1
d0c0: 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0700>.**.** The 
d0d0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
d0e0: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
d0f0: 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
d100: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
d110: 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
d120: 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
d130: 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54 68  re of SQLite. Th
d140: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
d150: 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
d160: 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
d170: 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
d180: 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  l compatibility 
d190: 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a  considerations..
d1a0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
d1b0: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 31 7d  :.**.** {H12201}
d1c0: 20 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62   Each new [datab
d1d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
d1e0: 73 68 61 6c 6c 20 68 61 76 65 20 74 68 65 0a 2a  shall have the.*
d1f0: 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65  *          [exte
d200: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
d210: 73 5d 20 66 65 61 74 75 72 65 20 64 69 73 61 62  s] feature disab
d220: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
d230: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 32 7d 20 54  **.** {H12202} T
d240: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  he [sqlite3_exte
d250: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
d260: 73 28 44 2c 46 29 5d 20 69 6e 74 65 72 66 61 63  s(D,F)] interfac
d270: 65 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a  e shall enable.*
d280: 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65  *          [exte
d290: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
d2a0: 73 5d 20 66 6f 72 20 74 68 65 20 20 5b 64 61 74  s] for the  [dat
d2b0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d2c0: 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ] D.**          
d2d0: 69 66 20 74 68 65 20 46 20 70 61 72 61 6d 65 74  if the F paramet
d2e0: 65 72 20 69 73 20 74 72 75 65 2c 20 6f 72 20 64  er is true, or d
d2f0: 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20 46  isable them if F
d300: 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e   is false..*/.in
d310: 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
d320: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
d330: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
d340: 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
d350: 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
d360: 72 74 20 52 6f 77 69 64 20 7b 48 31 32 32 32 30  rt Rowid {H12220
d370: 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
d380: 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61   Each entry in a
d390: 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68  n SQLite table h
d3a0: 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
d3b0: 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
d3c0: 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
d3d0: 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65  the "rowid". The
d3e0: 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
d3f0: 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
d400: 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
d410: 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
d420: 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
d430: 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
d440: 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
d450: 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
d460: 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
d470: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49  lared columns. I
d480: 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
d490: 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
d4a0: 79 70 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d  ype INTEGER PRIM
d4b0: 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61  ARY KEY then tha
d4c0: 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
d4d0: 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
d4e0: 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
d4f0: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
d500: 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64  eturns the rowid
d510: 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   of the most rec
d520: 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ent.** successfu
d530: 6c 20 49 4e 53 45 52 54 20 69 6e 74 6f 20 74 68  l INSERT into th
d540: 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20  e database from 
d550: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
d560: 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  nnection].** in 
d570: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
d580: 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65  nt.  If no succe
d590: 73 73 66 75 6c 20 49 4e 53 45 52 54 73 0a 2a 2a  ssful INSERTs.**
d5a0: 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
d5b0: 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61  red on that data
d5c0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
d5d0: 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
d5e0: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49  d..**.** If an I
d5f0: 4e 53 45 52 54 20 6f 63 63 75 72 73 20 77 69 74  NSERT occurs wit
d600: 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74  hin a trigger, t
d610: 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66  hen the rowid of
d620: 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a   the inserted.**
d630: 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64   row is returned
d640: 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
d650: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
d660: 74 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69  trigger is runni
d670: 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
d680: 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d  the trigger term
d690: 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75  inates, the valu
d6a0: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
d6b0: 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65  is routine.** re
d6c0: 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73  verts to the las
d6d0: 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64  t value inserted
d6e0: 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
d6f0: 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a  ger fired..**.**
d700: 20 41 6e 20 49 4e 53 45 52 54 20 74 68 61 74 20   An INSERT that 
d710: 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63  fails due to a c
d720: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
d730: 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20  ion is not a.** 
d740: 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52  successful INSER
d750: 54 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  T and does not c
d760: 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
d770: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
d780: 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68  .** routine.  Th
d790: 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
d7a0: 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
d7b0: 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
d7c0: 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
d7d0: 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
d7e0: 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
d7f0: 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
d800: 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
d810: 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
d820: 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
d830: 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20  s.  When INSERT 
d840: 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
d850: 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
d860: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
d870: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
d880: 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
d890: 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
d8a0: 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
d8b0: 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
d8c0: 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
d8d0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
d8e0: 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
d8f0: 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
d900: 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
d910: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
d920: 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
d930: 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  e..**.** For the
d940: 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
d950: 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 49 4e  s routine, an IN
d960: 53 45 52 54 20 69 73 20 63 6f 6e 73 69 64 65 72  SERT is consider
d970: 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
d980: 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
d990: 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
d9a0: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
d9b0: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
d9c0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 31 7d 20  .**.** {H12221} 
d9d0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  The [sqlite3_las
d9e0: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
d9f0: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
da00: 6e 73 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20  ns the rowid.** 
da10: 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
da20: 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63  most recent succ
da30: 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20 70 65  essful INSERT pe
da40: 72 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20 73  rformed on the s
da50: 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
da60: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
da70: 74 69 6f 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e  tion] and within
da80: 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67   the same or hig
da90: 68 65 72 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20  her level.**    
daa0: 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f        trigger co
dab0: 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69  ntext, or zero i
dac0: 66 20 74 68 65 72 65 20 68 61 76 65 20 62 65 65  f there have bee
dad0: 6e 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 20  n no qualifying 
dae0: 69 6e 73 65 72 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b  inserts..**.** {
daf0: 48 31 32 32 32 33 7d 20 54 68 65 20 5b 73 71 6c  H12223} The [sql
db00: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
db10: 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69  _rowid()] functi
db20: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  on returns the.*
db30: 2a 20 20 20 20 20 20 20 20 20 20 73 61 6d 65 20  *          same 
db40: 76 61 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c 65  value when calle
db50: 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
db60: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 0a  trigger context.
db70: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d 6d 65  **          imme
db80: 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 61  diately before a
db90: 6e 64 20 61 66 74 65 72 20 61 20 52 4f 4c 4c 42  nd after a ROLLB
dba0: 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  ACK..**.** ASSUM
dbb0: 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
dbc0: 31 32 32 33 32 7d 20 49 66 20 61 20 73 65 70 61  12232} If a sepa
dbd0: 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
dbe0: 6f 72 6d 73 20 61 20 6e 65 77 20 49 4e 53 45 52  orms a new INSER
dbf0: 54 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  T on the same.**
dc00: 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61            databa
dc10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
dc20: 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
dc30: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
dc40: 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  id()].**        
dc50: 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75    function is ru
dc60: 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
dc70: 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
dc80: 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a  insert rowid,.**
dc90: 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
dca0: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
dcb0: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
dcc0: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
dcd0: 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  )] is.**        
dce0: 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20    unpredictable 
dcf0: 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
dd00: 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
dd10: 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
dd20: 20 20 20 20 20 20 20 20 20 20 6c 61 73 74 20 69            last i
dd30: 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a  nsert rowid..*/.
dd40: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
dd50: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
dd60: 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
dd70: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
dd80: 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
dd90: 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
dda0: 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20 3c  ified {H12240} <
ddb0: 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10600>.**.** Th
ddc0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
ddd0: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
dde0: 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
ddf0: 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
de00: 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
de10: 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
de20: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
de30: 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
de40: 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
de50: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
de60: 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
de70: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
de80: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e  parameter..** On
de90: 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  ly changes that 
dea0: 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65  are directly spe
deb0: 63 69 66 69 65 64 20 62 79 20 74 68 65 20 49 4e  cified by the IN
dec0: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a  SERT, UPDATE,.**
ded0: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
dee0: 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
def0: 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
df00: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
df10: 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20 6e  * triggers are n
df20: 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 20  ot counted. Use 
df30: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
df40: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
df50: 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e  nction.** to fin
df60: 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
df70: 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
df80: 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
df90: 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
dfa0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77  rs..**.** A "row
dfb0: 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68   change" is a ch
dfc0: 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65  ange to a single
dfd0: 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65   row of a single
dfe0: 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64   table.** caused
dff0: 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44   by an INSERT, D
e000: 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45  ELETE, or UPDATE
e010: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77   statement.  Row
e020: 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68  s that.** are ch
e030: 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66  anged as side ef
e040: 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43 45  fects of REPLACE
e050: 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
e060: 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
e070: 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
e080: 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42 4c  ssing, DROP TABL
e090: 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  E, or by any oth
e0a0: 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
e0b0: 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
e0c0: 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
e0d0: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  ges..**.** A "tr
e0e0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
e0f0: 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
e100: 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
e110: 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
e120: 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
e130: 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d 6f  f a trigger.  Mo
e140: 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
e150: 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74  s are.** evaluat
e160: 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  ed outside of an
e170: 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73  y trigger.  This
e180: 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76   is the "top lev
e190: 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  el".** trigger c
e1a0: 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72  ontext.  If a tr
e1b0: 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d  igger fires from
e1c0: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
e1d0: 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72  a.** new trigger
e1e0: 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65   context is ente
e1f0: 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61  red for the dura
e200: 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65  tion of that one
e210: 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75  .** trigger.  Su
e220: 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65  btriggers create
e230: 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72   subcontexts for
e240: 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e   their duration.
e250: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b  .**.** Calling [
e260: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
e270: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  or [sqlite3_step
e280: 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20  ()] recursively 
e290: 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61  does.** not crea
e2a0: 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72  te a new trigger
e2b0: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
e2c0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
e2d0: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
e2e0: 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63   of direct row c
e2f0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a  hanges in the.**
e300: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
e310: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
e320: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
e330: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
e340: 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
e350: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c  ext..**.** Thus,
e360: 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
e370: 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
e380: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
e390: 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
e3a0: 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
e3b0: 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
e3c0: 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
e3d0: 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
e3e0: 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
e3f0: 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
e400: 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68 65  vel.  Within the
e410: 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67   body of a trigg
e420: 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  er,.** the sqlit
e430: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
e440: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61  erface can be ca
e450: 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  lled to find the
e460: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
e470: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
e480: 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
e490: 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
e4a0: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
e4b0: 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  * statement with
e4c0: 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74  in the body of t
e4d0: 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
e4e0: 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
e4f0: 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64   number returned
e500: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
e510: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75  e changes.** cau
e520: 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65  sed by subtrigge
e530: 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68  rs since those h
e540: 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f  ave their own co
e550: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ntext..**.** SQL
e560: 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
e570: 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45  he command "DELE
e580: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77  TE FROM table" w
e590: 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63  ithout a WHERE c
e5a0: 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70  lause.** by drop
e5b0: 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74  ping and recreat
e5c0: 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20  ing the table.  
e5d0: 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61  (This is much fa
e5e0: 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a  ster than going.
e5f0: 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64  ** through and d
e600: 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75  eleting individu
e610: 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d  al elements from
e620: 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65   the table.)  Be
e630: 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a  cause of this.**
e640: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74   optimization, t
e650: 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20  he deletions in 
e660: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
e670: 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20  le" are not row 
e680: 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77  changes and.** w
e690: 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74  ill not be count
e6a0: 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
e6b0: 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b  3_changes() or [
e6c0: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
e6d0: 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63  anges()].** func
e6e0: 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 73  tions, regardles
e6f0: 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  s of the number 
e700: 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74  of elements that
e710: 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79   were originally
e720: 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c 65  .** in the table
e730: 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63  .  To get an acc
e740: 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74  urate count of t
e750: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
e760: 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a  s deleted, use.*
e770: 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  * "DELETE FROM t
e780: 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e  able WHERE 1" in
e790: 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  stead..**.** INV
e7a0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
e7b0: 48 31 32 32 34 31 7d 20 54 68 65 20 5b 73 71 6c  H12241} The [sql
e7c0: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
e7d0: 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72  function shall r
e7e0: 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
e7f0: 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
e800: 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
e810: 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
e820: 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
e830: 44 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20  DATE,.**        
e840: 20 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74    or DELETE stat
e850: 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d  ement on the sam
e860: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
e870: 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20  ction and.**    
e880: 20 20 20 20 20 20 77 69 74 68 69 6e 20 74 68 65        within the
e890: 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20   same or higher 
e8a0: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c  trigger context,
e8b0: 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72   or zero if ther
e8c0: 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20  e have.**       
e8d0: 20 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20     not been any 
e8e0: 71 75 61 6c 69 66 79 69 6e 67 20 72 6f 77 20 63  qualifying row c
e8f0: 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  hanges..**.** {H
e900: 31 32 32 34 33 7d 20 53 74 61 74 65 6d 65 6e 74  12243} Statement
e910: 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44  s of the form "D
e920: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
e930: 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a  name" with no.**
e940: 20 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20            WHERE 
e950: 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 63 61 75  clause shall cau
e960: 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  se subsequent ca
e970: 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  lls to.**       
e980: 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e     [sqlite3_chan
e990: 67 65 73 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  ges()] to return
e9a0: 20 7a 65 72 6f 2c 20 72 65 67 61 72 64 6c 65 73   zero, regardles
e9b0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  s of the.**     
e9c0: 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 72       number of r
e9d0: 6f 77 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69  ows originally i
e9e0: 6e 20 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a  n the table..**.
e9f0: 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
ea00: 2a 2a 0a 2a 2a 20 7b 41 31 32 32 35 32 7d 20 49  **.** {A12252} I
ea10: 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
ea20: 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
ea30: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
ea40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ea50: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  n.**          wh
ea60: 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
ea70: 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
ea80: 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
ea90: 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20  e returned.**   
eaa0: 20 20 20 20 20 20 20 69 73 20 75 6e 70 72 65 64         is unpred
eab0: 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
eac0: 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
ead0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
eae0: 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
eaf0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
eb00: 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
eb10: 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31  ows Modified {H1
eb20: 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a  2260} <S10600>.*
eb30: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
eb40: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
eb50: 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
eb60: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49  nges caused by I
eb70: 4e 53 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54 45  NSERT,.** UPDATE
eb80: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
eb90: 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20  ments since the 
eba0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ebb0: 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64  tion] was opened
ebc0: 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69  ..** The count i
ebd0: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e  ncludes all chan
ebe0: 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69  ges from all tri
ebf0: 67 67 65 72 20 63 6f 6e 74 65 78 74 73 2e 20 20  gger contexts.  
ec00: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20  However,.** the 
ec10: 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
ec20: 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
ec30: 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
ec40: 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
ec50: 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
ec60: 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
ec70: 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 44 52  rocessing, or DR
ec80: 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73  OP table process
ec90: 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e  ing..** The chan
eca0: 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20  ges are counted 
ecb0: 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73  as soon as the s
ecc0: 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61  tatement that ma
ecd0: 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63  kes them is.** c
ece0: 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74  ompleted (when t
ecf0: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
ed00: 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  dle is passed to
ed10: 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
ed20: 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
ed30: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
ed40: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
ed50: 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d  lements the comm
ed60: 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  and "DELETE FROM
ed70: 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20   table" without 
ed80: 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a  a WHERE clause.*
ed90: 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e  * by dropping an
eda0: 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65  d recreating the
edb0: 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69   table.  (This i
edc0: 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68  s much faster th
edd0: 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f  an going.** thro
ede0: 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67  ugh and deleting
edf0: 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d   individual elem
ee00: 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61  ents from the ta
ee10: 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f  ble.)  Because o
ee20: 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69  f this.** optimi
ee30: 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65  zation, the dele
ee40: 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45  tions in "DELETE
ee50: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65   FROM table" are
ee60: 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73   not row changes
ee70: 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74   and.** will not
ee80: 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74   be counted by t
ee90: 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
eea0: 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33  es() or [sqlite3
eeb0: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
eec0: 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20  ].** functions, 
eed0: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
eee0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d  e number of elem
eef0: 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f  ents that were o
ef00: 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20  riginally.** in 
ef10: 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67  the table.  To g
ef20: 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63  et an accurate c
ef30: 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62  ount of the numb
ef40: 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74  er of rows delet
ef50: 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45  ed, use.** "DELE
ef60: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48  TE FROM table WH
ef70: 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a  ERE 1" instead..
ef80: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
ef90: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
efa0: 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
efb0: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
efc0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36  TS:.**.** {H1226
efd0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
efe0: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
eff0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74   returns the tot
f000: 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20  al number.**    
f010: 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68 61        of row cha
f020: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49  nges caused by I
f030: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 61  NSERT, UPDATE, a
f040: 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  nd/or DELETE.** 
f050: 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65           stateme
f060: 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  nts on the same 
f070: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
f080: 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a  tion], in any.**
f090: 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65            trigge
f0a0: 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65  r context, since
f0b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
f0c0: 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72 65  nnection was cre
f0d0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ated..**.** {H12
f0e0: 32 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20  263} Statements 
f0f0: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c  of the form "DEL
f100: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61  ETE FROM tablena
f110: 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20  me" with no.**  
f120: 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c          WHERE cl
f130: 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20 63  ause shall not c
f140: 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
f150: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20  returned.**     
f160: 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33       by [sqlite3
f170: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
f180: 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  ]..**.** ASSUMPT
f190: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
f1a0: 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72 61  264} If a separa
f1b0: 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
f1c0: 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
f1d0: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
f1e0: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
f1f0: 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74      while [sqlit
f200: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
f210: 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
f220: 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
f230: 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
f240: 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
f250: 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
f260: 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
f270: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
f280: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
f290: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f2a0: 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
f2b0: 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20  g-Running Query 
f2c0: 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30 30  {H12270} <S30500
f2d0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  >.**.** This fun
f2e0: 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
f2f0: 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
f300: 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
f310: 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
f320: 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
f330: 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
f340: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
f350: 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
f360: 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
f370: 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
f380: 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
f390: 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
f3a0: 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
f3b0: 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
f3c0: 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
f3d0: 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
f3e0: 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
f3f0: 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20  * It is safe to 
f400: 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
f410: 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
f420: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
f430: 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
f440: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
f450: 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
f460: 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
f470: 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
f480: 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
f490: 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
f4a0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
f4b0: 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
f4c0: 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
f4d0: 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
f4e0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f4f0: 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
f500: 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  ** If an SQL ope
f510: 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
f520: 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
f530: 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
f540: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
f550: 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
f560: 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
f570: 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
f580: 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
f590: 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
f5a0: 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
f5b0: 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
f5c0: 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72  *.** An SQL oper
f5d0: 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
f5e0: 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
f5f0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
f600: 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20  TERRUPT]..** If 
f610: 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
f620: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
f630: 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
f640: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
f650: 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
f660: 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
f670: 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
f680: 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
f690: 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
f6a0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
f6b0: 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
f6c0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
f6d0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 68  e3_interrupt() h
f6e0: 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
f6f0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
f700: 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
f710: 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
f720: 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
f730: 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  urns..**.** INVA
f740: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
f750: 31 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c 69  12271} The [sqli
f760: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
f770: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
f780: 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e  force all runnin
f790: 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  g.**          SQ
f7a0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73  L statements ass
f7b0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
f7c0: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
f7d0: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  onnection.**    
f7e0: 20 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61 66        to halt af
f7f0: 74 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20 61  ter processing a
f800: 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69 74  t most one addit
f810: 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64 61 74  ional row of dat
f820: 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 32  a..**.** {H12272
f830: 7d 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d  } Any SQL statem
f840: 65 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74 65  ent that is inte
f850: 72 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c 69  rrupted by [sqli
f860: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
f870: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c  .**          wil
f880: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
f890: 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a  _INTERRUPT]..**.
f8a0: 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
f8b0: 2a 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d 20 49  **.** {A12279} I
f8c0: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
f8d0: 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
f8e0: 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
f8f0: 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
f900: 20 20 20 20 20 20 20 20 20 69 73 20 72 75 6e 6e           is runn
f910: 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
f920: 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
f930: 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
f940: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f950: 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
f960: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
f970: 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
f980: 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
f990: 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 7d  omplete {H10510}
f9a0: 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70200>.**.** 
f9b0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
f9c0: 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
f9d0: 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
f9e0: 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
f9f0: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
fa00: 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
fa10: 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d  eems to form com
fa20: 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74  plete a SQL stat
fa30: 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
fa40: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
fa50: 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
fa60: 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
fa70: 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
fa80: 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54   for parsing.  T
fa90: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
faa0: 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65  turn true if the
fab0: 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
fac0: 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
fad0: 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
fae0: 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74  atement.  A stat
faf0: 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
fb00: 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
fb10: 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
fb20: 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
fb30: 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
fb40: 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a   fragment of a.*
fb50: 2a 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  * CREATE TRIGGER
fb60: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d   statement.  Sem
fb70: 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
fb80: 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
fb90: 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
fba0: 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
fbb0: 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
fbc0: 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
fbd0: 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
fbe0: 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
fbf0: 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
fc00: 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
fc10: 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
fc20: 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
fc30: 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
fc40: 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
fc50: 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tor..**.** These
fc60: 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
fc70: 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
fc80: 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
fc90: 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
fca0: 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
fcb0: 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
fcc0: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
fcd0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31 7d 20  .**.** {H10511} 
fce0: 41 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 61  A successful eva
fcf0: 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  luation of [sqli
fd00: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
fd10: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
fd20: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
fd30: 31 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 20  16()] functions 
fd40: 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  shall.**        
fd50: 20 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65 72    return a numer
fd60: 69 63 20 31 20 69 66 20 61 6e 64 20 6f 6e 6c 79  ic 1 if and only
fd70: 20 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f 6e   if the last non
fd80: 2d 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 20  -whitespace.**  
fd90: 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69 6e          token in
fda0: 20 74 68 65 69 72 20 69 6e 70 75 74 20 69 73 20   their input is 
fdb0: 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74  a semicolon that
fdc0: 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 65   is not in betwe
fdd0: 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  en.**          t
fde0: 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e 44  he BEGIN and END
fdf0: 20 6f 66 20 61 20 43 52 45 41 54 45 20 54 52 49   of a CREATE TRI
fe00: 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GGER statement..
fe10: 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d 20 49  **.** {H10512} I
fe20: 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
fe30: 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
fe40: 72 73 20 64 75 72 69 6e 67 20 61 6e 20 69 6e 76  rs during an inv
fe50: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  ocation.**      
fe60: 20 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f      of [sqlite3_
fe70: 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 20 5b  complete()] or [
fe80: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
fe90: 31 36 28 29 5d 20 74 68 65 6e 20 74 68 65 0a 2a  16()] then the.*
fea0: 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69  *          routi
feb0: 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  ne shall return 
fec0: 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
fed0: 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
fee0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 32  S:.**.** {A10512
fef0: 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  } The input to [
ff00: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
ff10: 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
ff20: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
ff30: 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20            UTF-8 
ff40: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41  string..**.** {A
ff50: 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75 74  10513} The input
ff60: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
ff70: 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
ff80: 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
ff90: 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
ffa0: 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
ffb0: 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
ffc0: 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  der..*/.int sqli
ffd0: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
ffe0: 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69  st char *sql);.i
fff0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
10000 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
10010 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
10020 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
10030 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
10040 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
10050 53 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33 31  SY Errors {H1231
10060 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a  0} <S40400>.**.*
10070 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73  * This routine s
10080 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
10090 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67  unction that mig
100a0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  ht be invoked wh
100b0 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
100c0 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
100d0 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  open a database 
100e0 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68  table that anoth
100f0 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20  er thread.** or 
10100 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b  process has lock
10110 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
10120 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
10130 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
10140 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
10150 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
10160 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  KED].** is retur
10170 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
10180 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
10190 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74  g the lock. If t
101a0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
101b0 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
101c0 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
101d0 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  ck will be invok
101e0 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
101f0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
10200 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10210 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69  to the handler i
10220 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
10230 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
10240 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
10250 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
10260 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
10270 64 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65 63  dler().  The sec
10280 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
10290 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 63  ** the handler c
102a0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
102b0 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
102c0 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
102d0 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
102e0 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69   invoked for thi
102f0 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  s locking event.
10300 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79    If the.** busy
10310 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
10320 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
10330 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
10340 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
10350 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
10360 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
10370 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
10380 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
10390 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
103a0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
103b0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
103c0 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
103d0 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
103e0 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
103f0 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
10400 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  ng and the cycle
10410 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
10420 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
10430 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
10440 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
10450 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
10460 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
10470 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
10480 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53  contention. If S
10490 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
104a0 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
104b0 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
104c0 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
104d0 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
104e0 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
104f0 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
10500 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b  TE_BUSY].** or [
10510 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
10520 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66  CKED] instead of
10530 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
10540 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
10550 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
10560 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
10570 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
10580 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
10590 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
105a0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
105b0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
105c0 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
105d0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
105e0 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
105f0 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
10600 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
10610 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
10620 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
10630 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
10640 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
10650 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
10660 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
10670 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
10680 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
10690 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
106a0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
106b0 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
106c0 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
106d0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
106e0 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
106f0 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
10700 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
10710 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
10720 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
10730 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
10740 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
10750 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
10760 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
10770 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
10780 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
10790 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
107a0 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
107b0 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
107c0 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  roceed..**.** Th
107d0 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
107e0 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
107f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
10800 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
10810 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
10820 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
10830 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
10840 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
10850 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
10860 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
10870 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
10880 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
10890 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
108a0 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
108b0 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
108c0 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
108d0 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
108e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
108f0 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
10900 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
10910 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
10920 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
10930 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
10940 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
10950 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
10960 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
10970 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
10980 72 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e  rs.  If it is un
10990 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20  able to promote 
109a0 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74  the lock, then t
109b0 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20  he in-memory.** 
109c0 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65  cache will be le
109d0 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69  ft in an inconsi
109e0 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20  stent state and 
109f0 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  so the error.** 
10a00 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64  code is promoted
10a10 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69   from the relati
10a20 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c  vely benign [SQL
10a30 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20  ITE_BUSY] to.** 
10a40 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20  the more severe 
10a50 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
10a60 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72  OCKED].  This er
10a70 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69  ror code promoti
10a80 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20  on.** forces an 
10a90 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61  automatic rollba
10aa0 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65  ck of the change
10ab0 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c  s.  See the.** <
10ac0 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63  a href="/cvstrac
10ad0 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69  /wiki?p=Corrupti
10ae0 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
10af0 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70  rror">.** Corrup
10b00 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
10b10 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20  yError</a> wiki 
10b20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75  page for a discu
10b30 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20  ssion of why.** 
10b40 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e  this is importan
10b50 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63  t..**.** There c
10b60 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
10b70 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
10b80 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
10b90 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
10ba0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74  onnection].  Set
10bb0 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
10bc0 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
10bd0 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ny.** previously
10be0 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e   set handler.  N
10bf0 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
10c00 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
10c10 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c  imeout()].** wil
10c20 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c  l also set or cl
10c30 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e  ear the busy han
10c40 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  dler..**.** INVA
10c50 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
10c60 31 32 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69  12311} The [sqli
10c70 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
10c80 28 44 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69 6f  (D,C,A)] functio
10c90 6e 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 0a  n shall replace.
10ca0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 73 79  **          busy
10cb0 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65   callback in the
10cc0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10cd0 63 74 69 6f 6e 5d 20 44 20 77 69 74 68 20 61 20  ction] D with a 
10ce0 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
10cf0 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
10d00 65 72 20 43 20 61 6e 64 20 61 70 70 6c 69 63 61  er C and applica
10d10 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
10d20 72 20 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  r A..**.** {H123
10d30 31 32 7d 20 4e 65 77 6c 79 20 63 72 65 61 74 65  12} Newly create
10d40 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  d [database conn
10d50 65 63 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20 68  ections] shall h
10d60 61 76 65 20 61 20 62 75 73 79 0a 2a 2a 20 20 20  ave a busy.**   
10d70 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 6f         handler o
10d80 66 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  f NULL..**.** {H
10d90 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20  12314} When two 
10da0 6f 72 20 6d 6f 72 65 20 5b 64 61 74 61 62 61 73  or more [databas
10db0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73  e connections] s
10dc0 68 61 72 65 20 61 0a 2a 2a 20 20 20 20 20 20 20  hare a.**       
10dd0 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62     [sqlite3_enab
10de0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20  le_shared_cache 
10df0 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c  | common cache],
10e00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
10e10 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
10e20 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  r the database c
10e30 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e  onnection curren
10e40 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  tly using.**    
10e50 20 20 20 20 20 20 74 68 65 20 63 61 63 68 65 20        the cache 
10e60 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64  shall be invoked
10e70 20 77 68 65 6e 20 74 68 65 20 63 61 63 68 65 20   when the cache 
10e80 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63  encounters a loc
10e90 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 36  k..**.** {H12316
10ea0 7d 20 49 66 20 61 20 62 75 73 79 20 68 61 6e 64  } If a busy hand
10eb0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ler callback ret
10ec0 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  urns zero, then 
10ed0 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
10ee0 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  face.**         
10ef0 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74   that provoked t
10f00 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  he locking event
10f10 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53   shall return [S
10f20 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
10f30 2a 2a 20 7b 48 31 32 33 31 38 7d 20 53 51 4c 69  ** {H12318} SQLi
10f40 74 65 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 73  te shall invokes
10f50 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
10f60 72 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  r with two argum
10f70 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 20  ents which.**   
10f80 20 20 20 20 20 20 20 61 72 65 20 61 20 63 6f 70         are a cop
10f90 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72  y of the pointer
10fa0 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
10fb0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
10fc0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
10fd0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
10fe0 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75  ler()] and a cou
10ff0 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
11000 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20   of prior.**    
11010 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e        invocation
11020 73 20 6f 66 20 74 68 65 20 62 75 73 79 20 68 61  s of the busy ha
11030 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61  ndler for the sa
11040 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  me locking event
11050 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
11060 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33  ONS:.**.** {A123
11070 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c  19} A busy handl
11080 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
11090 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
110a0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  onnection.**    
110b0 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72        or [prepar
110c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
110d0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
110e0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
110f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
11100 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
11110 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
11120 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
11130 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
11140 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
11150 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34  t {H12340} <S404
11160 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  10>.**.** This r
11170 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
11180 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
11190 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
111a0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
111b0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
111c0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
111d0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
111e0 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68  s locked.  The h
111f0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
11200 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
11210 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
11220 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
11230 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
11240 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
11250 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41  ated. {H12343} A
11260 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73  fter "ms" millis
11270 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
11280 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
11290 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
112a0 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
112b0 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
112c0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
112d0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
112e0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
112f0 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74  .**.** Calling t
11300 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
11310 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
11320 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
11330 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
11340 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
11350 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ndlers..**.** Th
11360 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
11370 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
11380 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
11390 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
113a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
113b0 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f  any any given mo
113c0 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
113d0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
113e0 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
113f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
11400 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
11410 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
11420 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
11430 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
11440 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
11450 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ared..**.** INVA
11460 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
11470 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  12341} The [sqli
11480 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
11490 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61  ()] function sha
114a0 6c 6c 20 6f 76 65 72 72 69 64 65 20 61 6e 79 20  ll override any 
114b0 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  prior.**        
114c0 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f    [sqlite3_busy_
114d0 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73  timeout()] or [s
114e0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
114f0 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a  ler()] setting.*
11500 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68  *          on th
11510 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
11520 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
11530 0a 2a 2a 20 7b 48 31 32 33 34 33 7d 20 49 66 20  .** {H12343} If 
11540 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
11550 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75  r to [sqlite3_bu
11560 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73  sy_timeout()] is
11570 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20   less than.**   
11580 20 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20         or equal 
11590 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  to zero, then th
115a0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73  e busy handler s
115b0 68 61 6c 6c 20 62 65 20 63 6c 65 61 72 65 64 20  hall be cleared 
115c0 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  so that.**      
115d0 20 20 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65      all subseque
115e0 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  nt locking event
115f0 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65  s immediately re
11600 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
11610 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34  Y]..**.** {H1234
11620 34 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61  4} If the 2nd pa
11630 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
11640 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
11650 28 29 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76  ()] is a positiv
11660 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
11670 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62  mber N, then a b
11680 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c  usy handler shal
11690 6c 20 62 65 20 73 65 74 20 74 68 61 74 20 72 65  l be set that re
116a0 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a  peatedly calls.*
116b0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 78  *          the x
116c0 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69  Sleep() method i
116d0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  n the [sqlite3_v
116e0 66 73 20 7c 20 56 46 53 20 69 6e 74 65 72 66 61  fs | VFS interfa
116f0 63 65 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20  ce] until.**    
11700 20 20 20 20 20 20 65 69 74 68 65 72 20 74 68 65        either the
11710 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20   lock clears or 
11720 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61  until the cumula
11730 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65 0a  tive sleep time.
11740 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 70 6f  **          repo
11750 72 74 65 64 20 62 61 63 6b 20 62 79 20 78 53 6c  rted back by xSl
11760 65 65 70 28 29 20 65 78 63 65 65 64 73 20 4e 20  eep() exceeds N 
11770 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f  milliseconds..*/
11780 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
11790 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
117a0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
117b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
117c0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
117d0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
117e0 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20  ueries {H12370} 
117f0 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44  <S10000>.**.** D
11800 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
11810 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
11820 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
11830 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
11840 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
11850 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
11860 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
11870 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
11880 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
11890 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
118a0 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
118b0 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
118c0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
118d0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
118e0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
118f0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
11900 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
11910 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
11920 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
11930 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
11940 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
11950 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
11960 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
11970 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
11980 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
11990 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
119a0 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
119b0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
119c0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
119d0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
119e0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
119f0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
11a00 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
11a10 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
11a20 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
11a30 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
11a40 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
11a50 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
11a60 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
11a70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
11a80 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
11a90 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
11aa0 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
11ab0 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
11ac0 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
11ad0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
11ae0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
11af0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
11b00 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
11b10 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
11b20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
11b30 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
11b40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
11b50 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
11b60 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
11b70 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
11b80 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
11b90 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
11ba0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
11bb0 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
11bc0 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
11bd0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
11be0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
11bf0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
11c00 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
11c10 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
11c20 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
11c30 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
11c40 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
11c50 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
11c60 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
11c70 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
11c80 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
11c90 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
11ca0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
11cb0 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
11cc0 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
11cd0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
11ce0 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
11cf0 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
11d00 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
11d10 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
11d20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
11d30 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
11d40 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
11d50 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
11d60 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
11d70 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
11d80 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
11d90 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
11da0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
11db0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
11dc0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
11dd0 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
11de0 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
11df0 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
11e00 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
11e10 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
11e20 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
11e30 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
11e40 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
11e50 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
11e60 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
11e70 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
11e80 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
11e90 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
11ea0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
11eb0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
11ec0 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
11ed0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
11ee0 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
11ef0 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
11f00 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
11f10 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
11f20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
11f30 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
11f40 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
11f50 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
11f60 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
11f70 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
11f80 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
11f90 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
11fa0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
11fb0 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
11fc0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
11fd0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
11fe0 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
11ff0 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20  .  It returns a 
12000 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
12010 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
12020 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
12030 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
12040 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69   After the calli
12050 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20  ng function has 
12060 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
12070 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68  he result, it sh
12080 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65  ould.** pass the
12090 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
120a0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
120b0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
120c0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
120d0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
120e0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
120f0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
12100 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
12110 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
12120 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
12130 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
12140 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
12150 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
12160 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
12170 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
12180 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
12190 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
121a0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
121b0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
121c0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
121d0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
121e0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
121f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
12200 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
12210 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
12220 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
12230 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
12240 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
12250 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
12260 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
12270 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
12280 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
12290 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
122a0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
122b0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
122c0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
122d0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
122e0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
122f0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
12300 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
12310 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
12320 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
12330 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
12340 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
12350 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
12360 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
12370 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
12380 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71  rrcode()] or [sq
12390 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
123a0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
123b0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 31  S:.**.** {H12371
123c0 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  } If a [sqlite3_
123d0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69  get_table()] fai
123e0 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ls a memory allo
123f0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  cation, then.** 
12400 20 20 20 20 20 20 20 20 20 69 74 20 73 68 61 6c           it shal
12410 6c 20 66 72 65 65 20 74 68 65 20 72 65 73 75 6c  l free the resul
12420 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f  t table under co
12430 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72  nstruction, abor
12440 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
12450 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65    query in proce
12460 73 73 2c 20 73 6b 69 70 20 61 6e 79 20 73 75 62  ss, skip any sub
12470 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c  sequent queries,
12480 20 73 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20   set the.**     
12490 20 20 20 20 20 2a 70 61 7a 52 65 73 75 6c 74 20       *pazResult 
124a0 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74  output pointer t
124b0 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72  o NULL and retur
124c0 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
124d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33 7d  ..**.** {H12373}
124e0 20 49 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d 6e   If the pnColumn
124f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
12500 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
12510 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a  ()] is not NULL.
12520 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
12530 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   a successful in
12540 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
12550 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
12560 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ] shall.**      
12570 20 20 20 20 77 72 69 74 65 20 74 68 65 20 6e 75      write the nu
12580 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
12590 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
125a0 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66     result set of
125b0 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20   the query into 
125c0 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  *pnColumn..**.**
125d0 20 7b 48 31 32 33 37 34 7d 20 49 66 20 74 68 65   {H12374} If the
125e0 20 70 6e 52 6f 77 20 70 61 72 61 6d 65 74 65 72   pnRow parameter
125f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   to [sqlite3_get
12600 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74  _table()] is not
12610 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
12620 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73 73    then a success
12630 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
12640 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  f [sqlite3_get_t
12650 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a  able()] shall.**
12660 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65 73            writes
12670 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
12680 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  ows in the.**   
12690 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65         result se
126a0 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69  t of the query i
126b0 6e 74 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a  nto *pnRow..**.*
126c0 2a 20 7b 48 31 32 33 37 36 7d 20 41 20 73 75 63  * {H12376} A suc
126d0 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
126e0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67  on of [sqlite3_g
126f0 65 74 5f 74 61 62 6c 65 28 29 5d 20 74 68 61 74  et_table()] that
12700 20 63 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20 20   computes.**    
12710 20 20 20 20 20 20 4e 20 72 6f 77 73 20 6f 66 20        N rows of 
12720 72 65 73 75 6c 74 20 77 69 74 68 20 43 20 63 6f  result with C co
12730 6c 75 6d 6e 73 20 70 65 72 20 72 6f 77 20 73 68  lumns per row sh
12740 61 6c 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73  all make *pazRes
12750 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ult.**          
12760 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 72 72 61  point to an arra
12770 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
12780 20 28 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67 73   (N+1)*C strings
12790 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
127a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 20 73  .**          C s
127b0 74 72 69 6e 67 73 20 61 72 65 20 63 6f 6c 75 6d  trings are colum
127c0 6e 20 6e 61 6d 65 73 20 61 73 20 6f 62 74 61 69  n names as obtai
127d0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20  ned from.**     
127e0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
127f0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64  lumn_name()] and
12800 20 74 68 65 20 72 65 73 74 20 61 72 65 20 63 6f   the rest are co
12810 6c 75 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c 75  lumn result valu
12820 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  es.**          o
12830 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
12840 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
12850 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  t()]..**.** {H12
12860 33 37 39 7d 20 54 68 65 20 76 61 6c 75 65 73 20  379} The values 
12870 69 6e 20 74 68 65 20 70 61 7a 52 65 73 75 6c 74  in the pazResult
12880 20 61 72 72 61 79 20 72 65 74 75 72 6e 65 64 20   array returned 
12890 62 79 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  by [sqlite3_get_
128a0 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20  table()].**     
128b0 20 20 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 69       shall remai
128c0 6e 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 63 6c  n valid until cl
128d0 65 61 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eared by [sqlite
128e0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
128f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d 20  .**.** {H12382} 
12900 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
12910 63 75 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c  curs during eval
12920 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  uation of [sqlit
12930 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a  e3_get_table()].
12940 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
12950 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73  function shall s
12960 65 74 20 2a 70 61 7a 52 65 73 75 6c 74 20 74 6f  et *pazResult to
12970 20 4e 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e 20   NULL, write an 
12980 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
12990 20 20 20 20 20 20 20 20 20 20 69 6e 74 6f 20 6d            into m
129a0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
129b0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
129c0 6c 6f 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20  loc()], make.** 
129d0 20 20 20 20 20 20 20 20 20 2a 2a 70 7a 45 72 72           **pzErr
129e0 6d 73 67 20 70 6f 69 6e 74 20 74 6f 20 74 68 61  msg point to tha
129f0 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2c  t error message,
12a00 20 61 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a 2a   and return a.**
12a10 20 20 20 20 20 20 20 20 20 20 61 70 70 72 6f 70            approp
12a20 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
12a30 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
12a40 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
12a50 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
12a60 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
12a70 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
12a80 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
12a90 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
12aa0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
12ab0 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
12ac0 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
12ad0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
12ae0 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
12af0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
12b00 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
12b10 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
12b20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
12b30 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
12b40 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
12b50 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
12b60 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
12b70 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
12b80 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
12b90 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
12ba0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
12bb0 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
12bc0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
12bd0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
12be0 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
12bf0 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37  g Functions {H17
12c00 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32  400} <S70000><S2
12c10 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0000>.**.** Thes
12c20 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
12c30 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  orkalikes of the
12c40 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
12c50 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
12c60 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
12c70 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
12c80 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
12c90 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
12ca0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
12cb0 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
12cc0 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
12cd0 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
12ce0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
12cf0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
12d00 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
12d10 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
12d20 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
12d30 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
12d40 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
12d50 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20  _free()].  Both 
12d60 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
12d70 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
12d80 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
12d90 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
12da0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
12db0 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
12dc0 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
12dd0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
12de0 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e  ** In sqlite3_sn
12df0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
12e00 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
12e10 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
12e20 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
12e30 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
12e40 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
12e50 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
12e60 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
12e70 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
12e80 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
12e90 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
12ea0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
12eb0 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
12ec0 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
12ed0 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
12ee0 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
12ef0 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
12f00 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61  tf().  This is a
12f10 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
12f20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
12f30 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
12f40 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
12f50 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
12f60 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65  atibility.  Note
12f70 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
12f80 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
12f90 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
12fa0 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
12fb0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
12fc0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
12fd0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
12fe0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
12ff0 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64  e buffer.  We ad
13000 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
13010 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
13020 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
13030 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
13040 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
13050 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
13060 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
13070 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
13080 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
13090 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
130a0 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
130b0 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41  ibility..**.** A
130c0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
130d0 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
130e0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
130f0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
13100 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
13110 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
13120 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
13130 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65  terminated.  The
13140 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
13150 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
13160 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
13170 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
13180 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
13190 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
131a0 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
131b0 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
131c0 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
131d0 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
131e0 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
131f0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ters..**.** Thes
13200 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
13210 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
13220 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
13230 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
13240 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
13250 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
13260 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
13270 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
13280 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
13290 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
132a0 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
132b0 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
132c0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
132d0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
132e0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20  s..**.** The %q 
132f0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
13300 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
13310 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
13320 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ll-terminated.**
13330 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
13340 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
13350 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
13360 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
13370 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
13380 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
13390 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
133a0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42  ring literal.  B
133b0 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
133c0 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
133d0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
133e0 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
133f0 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
13400 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
13410 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
13420 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
13430 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
13440 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
13450 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
13460 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
13470 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
13480 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
13490 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
134a0 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
134b0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
134c0 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
134d0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
134e0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
134f0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
13500 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
13510 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
13520 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
13530 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
13540 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
13550 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
13560 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
13570 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
13580 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
13590 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
135a0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
135b0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
135c0 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
135d0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
135e0 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
135f0 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
13600 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
13610 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
13620 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
13630 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
13640 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
13650 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
13660 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
13670 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
13680 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
13690 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
136a0 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
136b0 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
136c0 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
136d0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
136e0 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
136f0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
13700 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
13710 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
13720 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
13730 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
13740 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
13750 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
13760 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
13770 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
13780 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
13790 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
137a0 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
137b0 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
137c0 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
137d0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
137e0 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
137f0 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  teral..**.** The
13800 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
13810 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
13820 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
13830 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
13840 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
13850 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
13860 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
13870 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
13880 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
13890 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
138a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
138b0 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
138c0 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
138d0 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
138e0 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c  le quotes) in pl
138f0 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70  ace of the %Q op
13900 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65  tion.  So, for e
13910 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
13920 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
13930 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
13940 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
13950 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
13960 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
13970 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
13980 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
13990 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
139a0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
139b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
139c0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
139d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
139e0 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
139f0 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
13a00 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
13a10 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
13a20 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
13a30 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
13a40 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
13a50 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
13a60 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74   The "%z" format
13a70 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
13a80 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22  s exactly like "
13a90 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  %s" with the.** 
13aa0 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
13ab0 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
13ac0 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
13ad0 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
13ae0 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
13af0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
13b00 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
13b10 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44  put string. {END
13b20 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  }.**.** INVARIAN
13b30 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30  TS:.**.** {H1740
13b40 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  3}  The [sqlite3
13b50 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20  _mprintf()] and 
13b60 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  [sqlite3_vmprint
13b70 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a  f()] interfaces.
13b80 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
13b90 75 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74  urn either point
13ba0 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
13bb0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
13bc0 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20  ings held in.** 
13bd0 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79            memory
13be0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
13bf0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13c00 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ] or NULL pointe
13c10 72 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20  rs if.**        
13c20 20 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71     a call to [sq
13c30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13c40 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fails..**.** {H1
13c50 37 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69  7406}  The [sqli
13c60 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
13c70 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73  interface writes
13c80 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
13c90 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ed.**           
13ca0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74  UTF-8 string int
13cb0 6f 20 74 68 65 20 62 75 66 66 65 72 20 70 6f 69  o the buffer poi
13cc0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 73  nted to by the s
13cd0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
13ce0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 70 72 6f  **           pro
13cf0 76 69 64 65 64 20 74 68 61 74 20 74 68 65 20 66  vided that the f
13d00 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
13d10 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
13d20 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34  ero..**.** {H174
13d30 30 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  07}  The [sqlite
13d40 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e  3_snprintf()] in
13d50 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
13d60 20 77 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a   write slots of.
13d70 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 73  **           its
13d80 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 28   output buffer (
13d90 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
13da0 65 74 65 72 29 20 6f 75 74 73 69 64 65 20 74 68  eter) outside th
13db0 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20  e range.**      
13dc0 20 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67       of 0 throug
13dd0 68 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69  h N-1 (where N i
13de0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
13df0 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20  meter).**       
13e00 20 20 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f      regardless o
13e10 66 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  f the length of 
13e20 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20  the string.**   
13e30 20 20 20 20 20 20 20 20 72 65 71 75 65 73 74 65          requeste
13e40 64 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20  d by the format 
13e50 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a  specification..*
13e60 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
13e70 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
13e80 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
13e90 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
13ea0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
13eb0 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
13ec0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
13ed0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
13ee0 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  har*, ...);../*.
13ef0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
13f00 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
13f10 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30  ubsystem {H17300
13f20 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20000>.**.**
13f30 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
13f40 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72    uses these thr
13f50 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
13f60 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
13f70 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
13f80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
13f90 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
13fa0 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
13fb0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
13fc0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
13fd0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
13fe0 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
13ff0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
14000 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
14010 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
14020 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
14030 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
14040 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
14050 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
14060 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
14070 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
14080 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
14090 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
140a0 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
140b0 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
140c0 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  ..** If sqlite3_
140d0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
140e0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
140f0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
14100 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
14110 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
14120 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d  r.  If the param
14130 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
14140 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
14150 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
14160 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
14170 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
14180 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
14190 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  r..**.** Calling
141a0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
141b0 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
141c0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
141d0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
141e0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
141f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
14200 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
14210 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
14220 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
14230 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
14240 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
14250 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
14260 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
14270 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
14280 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
14290 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
142a0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
142b0 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
142c0 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
142d0 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
142e0 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
142f0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
14300 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
14310 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
14320 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
14330 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
14340 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
14350 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
14360 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
14370 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
14380 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
14390 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
143a0 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
143b0 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
143c0 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
143d0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
143e0 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
143f0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
14400 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
14410 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
14420 66 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  free()..**.** Th
14430 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
14440 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
14450 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
14460 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
14470 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
14480 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
14490 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
144a0 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
144b0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
144c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
144d0 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
144e0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
144f0 61 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68  arameter.  If th
14500 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
14510 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
14520 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e  lloc().** is a N
14530 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
14540 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
14550 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
14560 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
14570 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65  _malloc(N) where
14580 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
14590 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
145a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
145b0 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e  .** If the secon
145c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
145d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
145e0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
145f0 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
14600 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
14610 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
14620 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
14630 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
14640 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
14650 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
14660 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
14670 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
14680 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20  loc() returns a 
14690 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
146a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
146b0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
146c0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
146d0 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69   NULL if suffici
146e0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e  ent memory is un
146f0 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66  available..** If
14700 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
14710 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
14720 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
14730 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
14740 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
14750 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
14760 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
14770 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
14780 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
14790 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
147a0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
147b0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
147c0 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  d..** If sqlite3
147d0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
147e0 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
147f0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
14800 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
14810 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65  ed..**.** The me
14820 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
14830 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
14840 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
14850 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
14860 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
14870 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
14880 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e  te boundary. {EN
14890 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66  D}.**.** The def
148a0 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ault implementat
148b0 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72  ion of the memor
148c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
148d0 73 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74  system uses.** t
148e0 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  he malloc(), rea
148f0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
14900 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  ) provided by th
14910 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
14920 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32  rary..** {H17382
14930 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51  } However, if SQ
14940 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
14950 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
14960 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d  ITE_MEMORY_SIZE=
14970 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65  <i>NNN</i> C pre
14980 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
14990 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69  (where <i>NNN</i
149a0 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67  >.** is an integ
149b0 65 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  er), then SQLite
149c0 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69 63   create a static
149d0 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61   array of at lea
149e0 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e  st.** <i>NNN</i>
149f0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
14a00 6e 64 20 75 73 65 73 20 74 68 61 74 20 61 72 72  nd uses that arr
14a10 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ay for all of it
14a20 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d  s dynamic.** mem
14a30 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
14a40 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64  eeds. {END}  Add
14a50 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  itional memory a
14a60 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73  llocator options
14a70 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65 64  .** may be added
14a80 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
14a90 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  ses..**.** In SQ
14aa0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
14ab0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
14ac0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
14ad0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
14ae0 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
14af0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
14b00 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
14b10 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
14b20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
14b30 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
14b40 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
14b50 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
14b60 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
14b70 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
14b80 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
14b90 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
14ba0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  e used..**.** Th
14bb0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
14bc0 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
14bd0 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ls.** the system
14be0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
14bf0 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
14c00 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
14c10 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
14c20 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
14c30 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
14c40 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
14c50 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
14c60 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
14c70 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
14c80 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
14c90 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
14ca0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
14cb0 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ors are detected
14cc0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72  , but.** they ar
14cd0 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
14ce0 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
14cf0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
14d00 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
14d10 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
14d20 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  MEM]..**.** INVA
14d30 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
14d40 31 37 33 30 33 7d 20 20 54 68 65 20 5b 73 71 6c  17303}  The [sql
14d50 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20  ite3_malloc(N)] 
14d60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
14d70 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74  s either a point
14d80 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
14d90 20 20 20 61 20 6e 65 77 6c 79 20 63 68 65 63 6b     a newly check
14da0 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66 20  ed-out block of 
14db0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
14dc0 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20   of memory.**   
14dd0 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20          that is 
14de0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20  8-byte aligned, 
14df0 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  or it returns NU
14e00 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61 62  LL if it is unab
14e10 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  le.**           
14e20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65 20 72  to fulfill the r
14e30 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  equest..**.** {H
14e40 31 37 33 30 34 7d 20 20 54 68 65 20 5b 73 71 6c  17304}  The [sql
14e50 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20  ite3_malloc(N)] 
14e60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
14e70 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
14e80 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
14e90 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
14ea0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
14eb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 35 7d  ..**.** {H17305}
14ec0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66    The [sqlite3_f
14ed0 72 65 65 28 50 29 5d 20 69 6e 74 65 72 66 61 63  ree(P)] interfac
14ee0 65 20 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72  e releases memor
14ef0 79 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  y previously.** 
14f00 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
14f10 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
14f20 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
14f30 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14f40 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ],.**           
14f50 6d 61 6b 69 6e 67 20 69 74 20 61 76 61 69 6c 61  making it availa
14f60 62 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a  ble for reuse..*
14f70 2a 0a 2a 2a 20 7b 48 31 37 33 30 36 7d 20 20 41  *.** {H17306}  A
14f80 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
14f90 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69 73  3_free(NULL)] is
14fa0 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
14fb0 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 30  p..**.** {H17310
14fc0 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71  }  A call to [sq
14fd0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c  lite3_realloc(0,
14fe0 4e 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e  N)] is equivalen
14ff0 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20  t to a call.**  
15000 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c           to [sql
15010 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e  ite3_malloc(N)].
15020 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 32 7d 20  .**.** {H17312} 
15030 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   A call to [sqli
15040 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 29  te3_realloc(P,0)
15050 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  ] is equivalent 
15060 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20  to a call.**    
15070 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74         to [sqlit
15080 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a  e3_free(P)]..**.
15090 2a 2a 20 7b 48 31 37 33 31 35 7d 20 20 54 68 65  ** {H17315}  The
150a0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
150b0 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  s [sqlite3_mallo
150c0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72  c()], [sqlite3_r
150d0 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20  ealloc()],.**   
150e0 20 20 20 20 20 20 20 20 61 6e 64 20 5b 73 71 6c          and [sql
150f0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f 72  ite3_free()] for
15100 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f   all of its memo
15110 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e  ry allocation an
15120 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 64  d.**           d
15130 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64  eallocation need
15140 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 38  s..**.** {H17318
15150 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
15160 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e  realloc(P,N)] in
15170 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
15180 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72  either a pointer
15190 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f  .**           to
151a0 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65 63   a block of chec
151b0 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f  ked-out memory o
151c0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
151d0 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20  es in size.**   
151e0 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20          that is 
151f0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20  8-byte aligned, 
15200 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
15210 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 31  r..**.** {H17321
15220 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  }  When [sqlite3
15230 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
15240 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c  eturns a non-NUL
15250 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69  L pointer, it fi
15260 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rst.**          
15270 20 63 6f 70 69 65 73 20 74 68 65 20 66 69 72 73   copies the firs
15280 74 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f 6e  t K bytes of con
15290 74 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f  tent from P into
152a0 20 74 68 65 20 6e 65 77 6c 79 0a 2a 2a 20 20 20   the newly.**   
152b0 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65          allocate
152c0 64 20 62 6c 6f 63 6b 2c 20 77 68 65 72 65 20 4b  d block, where K
152d0 20 69 73 20 74 68 65 20 6c 65 73 73 65 72 20 6f   is the lesser o
152e0 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a 65  f N and the size
152f0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
15300 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a   the buffer P..*
15310 2a 0a 2a 2a 20 7b 48 31 37 33 32 32 7d 20 20 57  *.** {H17322}  W
15320 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  hen [sqlite3_rea
15330 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72  lloc(P,N)] retur
15340 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  ns a non-NULL po
15350 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a  inter, it first.
15360 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 6c  **           rel
15370 65 61 73 65 73 20 74 68 65 20 62 75 66 66 65 72  eases the buffer
15380 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32   P..**.** {H1732
15390 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  3}  When [sqlite
153a0 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20  3_realloc(P,N)] 
153b0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
153c0 65 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a 2a  e buffer P is.**
153d0 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 6d             not m
153e0 6f 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65 61  odified or relea
153f0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  sed..**.** ASSUM
15400 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
15410 31 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69 6e  17350}  The poin
15420 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
15430 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
15440 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
15450 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 20  ealloc()].**    
15460 20 20 20 20 20 20 20 6d 75 73 74 20 62 65 20 65         must be e
15470 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
15480 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61  se pointers obta
15490 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
154a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69  r.**           i
154b0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
154c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
154d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
154e0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
154f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f  .**           no
15500 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
15510 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33  sed..**.** {A173
15520 35 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61  51}  The applica
15530 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
15540 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
15550 70 61 72 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20  part of.**      
15560 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20       a block of 
15570 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
15580 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
15590 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
155a0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 72       [sqlite3_fr
155b0 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
155c0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
155d0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
155e0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
155f0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
15600 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
15610 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
15620 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
15630 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
15640 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
15650 73 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20 3c  stics {H17370} <
15660 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51  S30210>.**.** SQ
15670 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
15680 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
15690 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
156a0 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
156b0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
156c0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
156d0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
156e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
156f0 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
15700 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
15710 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
15720 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
15730 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49  bsystem..**.** I
15740 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
15750 20 7b 48 31 37 33 37 31 7d 20 54 68 65 20 5b 73   {H17371} The [s
15760 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
15770 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
15780 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
15790 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 20 20 20   of bytes.**    
157a0 20 20 20 20 20 20 6f 66 20 6d 65 6d 6f 72 79 20        of memory 
157b0 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
157c0 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
157d0 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
157e0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 7d 20 54  **.** {H17373} T
157f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
15800 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
15810 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
15820 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20  the maximum.**  
15830 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
15840 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
15850 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
15860 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
15870 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  rk.**          w
15880 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a  as last reset..*
15890 2a 0a 2a 2a 20 7b 48 31 37 33 37 34 7d 20 54 68  *.** {H17374} Th
158a0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
158b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
158c0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
158d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
158e0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
158f0 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
15900 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
15910 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 65 64  *          added
15920 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
15930 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
15940 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
15950 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  loc()],.**      
15960 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65 72      but not over
15970 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
15980 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
15990 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
159a0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74  **          rout
159b0 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
159c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
159d0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   call..**.** {H1
159e0 37 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72 79  7375} The memory
159f0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
15a00 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
15a10 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
15a20 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  f.**          [s
15a30 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
15a40 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
15a50 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
15a60 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
15a70 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72    [sqlite3_memor
15a80 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
15a90 73 20 74 72 75 65 2e 20 20 54 68 65 20 76 61 6c  s true.  The val
15aa0 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20  ue returned.**  
15ab0 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69          by [sqli
15ac0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
15ad0 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
15ae0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
15af0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 6f  **          prio
15b00 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
15b10 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
15b20 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
15b30 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
15b40 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
15b50 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
15b60 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
15b70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
15b80 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
15b90 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
15ba0 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30  or {H17390} <S20
15bb0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  000>.**.** SQLit
15bc0 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
15bd0 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
15be0 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
15bf0 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
15c00 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
15c10 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20  t random ROWIDs 
15c20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
15c30 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
15c40 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
15c50 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
15c60 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
15c70 65 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50 52  e ROWID.  The PR
15c80 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
15c90 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
15ca0 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
15cb0 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
15cc0 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
15cd0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
15ce0 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
15cf0 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
15d00 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
15d10 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
15d20 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
15d30 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
15d40 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
15d50 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
15d60 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54  uffer P..**.** T
15d70 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
15d80 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
15d90 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
15da0 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
15db0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
15dc0 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
15dd0 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
15de0 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
15df0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
15e00 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
15e10 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
15e20 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
15e30 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75  ct..** On all su
15e40 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
15e50 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
15e60 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
15e70 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
15e80 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
15e90 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
15ea0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
15eb0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
15ec0 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  method..**.** IN
15ed0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
15ee0 7b 48 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71  {H17392} The [sq
15ef0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
15f00 28 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  (N,P)] interface
15f10 20 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 20   writes N bytes 
15f20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  of.**          h
15f30 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
15f40 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  do-randomness in
15f50 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a  to buffer P..*/.
15f60 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
15f70 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
15f80 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
15f90 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
15fa0 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
15fb0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b  tion Callbacks {
15fc0 48 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30 3e  H12500} <S70100>
15fd0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
15fe0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ine registers a 
15ff0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16000 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
16010 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
16020 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
16030 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
16040 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
16050 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
16060 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
16070 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
16080 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
16090 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
160a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
160b0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
160c0 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
160d0 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
160e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
160f0 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
16100 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
16110 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a  )].  At various.
16120 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
16130 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
16140 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
16150 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
16160 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
16170 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
16180 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
16190 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
161a0 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
161b0 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
161c0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54   are allowed.  T
161d0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
161e0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
161f0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
16200 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
16210 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
16220 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
16230 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
16240 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
16250 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
16260 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
16270 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
16280 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
16290 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
162a0 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
162b0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
162c0 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
162d0 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 74   an error.  If t
162e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
162f0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
16300 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
16310 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
16320 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
16330 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
16340 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
16350 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
16360 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
16370 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
16380 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
16390 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
163a0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
163b0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
163c0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
163d0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
163e0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
163f0 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
16400 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
16410 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68   is ok.  When th
16420 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
16430 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
16440 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
16450 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
16460 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
16470 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
16480 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
16490 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
164a0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
164b0 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
164c0 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
164d0 20 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68 65   denied.  If the
164e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
164f0 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
16500 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
16510 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
16520 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
16530 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
16540 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
16550 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
16560 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
16570 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
16580 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
16590 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
165a0 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
165b0 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
165c0 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
165d0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
165e0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
165f0 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
16600 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
16610 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
16620 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
16630 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
16640 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
16650 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
16660 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
16670 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
16680 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
16690 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
166a0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
166b0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
166c0 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
166d0 72 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f 6e  rface. The secon
166e0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
166f0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
16700 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
16710 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
16720 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
16730 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
16740 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
16750 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
16760 64 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72  d. The third thr
16770 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
16780 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
16790 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
167a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
167b0 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
167c0 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
167d0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
167e0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
167f0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
16800 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
16810 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
16820 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
16830 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
16840 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
16850 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
16860 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
16870 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
16880 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
16890 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
168a0 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
168b0 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
168c0 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
168d0 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
168e0 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
168f0 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
16900 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
16910 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
16920 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
16930 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
16940 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
16950 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
16960 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
16970 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
16980 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
16990 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
169a0 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
169b0 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
169c0 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
169d0 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
169e0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
169f0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
16a00 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
16a10 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
16a20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
16a30 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
16a40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16a50 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
16a60 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
16a70 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
16a80 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
16a90 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
16aa0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
16ab0 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
16ac0 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
16ad0 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
16ae0 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
16af0 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
16b00 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
16b10 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
16b20 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
16b30 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
16b40 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
16b50 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
16b60 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
16b70 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
16b80 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
16b90 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61   Only a single a
16ba0 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
16bb0 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
16bc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16bd0 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
16be0 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
16bf0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
16c00 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
16c10 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
16c20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74  call.  Disable t
16c30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
16c40 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
16c50 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
16c60 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
16c70 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
16c80 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  fault..**.** Not
16c90 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
16ca0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
16cb0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
16cc0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
16cd0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
16ce0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
16cf0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
16d00 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
16d10 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
16d20 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
16d30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
16d40 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
16d50 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30  TS:.**.** {H1250
16d60 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
16d70 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 44  set_authorizer(D
16d80 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
16d90 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a 2a 20   registers a.** 
16da0 20 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 69           authori
16db0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
16dc0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
16dd0 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  ction D..**.** {
16de0 48 31 32 35 30 32 7d 20 54 68 65 20 61 75 74 68  H12502} The auth
16df0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
16e00 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
16e10 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
16e20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 69  .**          bei
16e30 6e 67 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a  ng compiled..**.
16e40 2a 2a 20 7b 48 31 32 35 30 33 7d 20 49 66 20 74  ** {H12503} If t
16e50 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
16e60 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
16e70 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
16e80 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  han.**          
16e90 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
16ea0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
16eb0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
16ec0 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
16ed0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
16ee0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
16ef0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
16f00 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20  hat caused.**   
16f10 20 20 20 20 20 20 20 74 68 65 20 61 75 74 68 6f         the autho
16f20 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74  rizer callback t
16f30 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c  o run shall fail
16f40 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20   with an.**     
16f50 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
16f60 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61  OR] error code a
16f70 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  nd an appropriat
16f80 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
16f90 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 34 7d 20  .**.** {H12504} 
16fa0 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69  When the authori
16fb0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
16fc0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
16fd0 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  , the operation.
16fe0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 73 63  **          desc
16ff0 72 69 62 65 64 20 69 73 20 70 72 6f 63 65 73 73  ribed is process
17000 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a  ed normally..**.
17010 2a 2a 20 7b 48 31 32 35 30 35 7d 20 57 68 65 6e  ** {H12505} When
17020 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
17030 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
17040 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
17050 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
17060 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17070 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
17080 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63  lent call that c
17090 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20 20  aused the.**    
170a0 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72        authorizer
170b0 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e   callback to run
170c0 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20   shall fail.**  
170d0 20 20 20 20 20 20 20 20 77 69 74 68 20 61 6e 20          with an 
170e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65  [SQLITE_ERROR] e
170f0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e  rror code and an
17100 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
17110 2a 20 20 20 20 20 20 20 20 20 20 65 78 70 6c 61  *          expla
17120 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65 73  ining that acces
17130 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a  s is denied..**.
17140 2a 2a 20 7b 48 31 32 35 30 36 7d 20 49 66 20 74  ** {H12506} If t
17150 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  he authorizer co
17160 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61  de (the 2nd para
17170 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
17180 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20  horizer.**      
17190 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73      callback) is
171a0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61   [SQLITE_READ] a
171b0 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  nd the authorize
171c0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
171d0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ns.**          [
171e0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
171f0 74 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65  then the prepare
17200 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  d statement is c
17210 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a  onstructed to.**
17220 20 20 20 20 20 20 20 20 20 20 69 6e 73 65 72 74            insert
17230 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
17240 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
17250 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
17260 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20  would have.**   
17270 20 20 20 20 20 20 20 62 65 65 6e 20 72 65 61 64         been read
17280 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
17290 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
172a0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 37  d..**.** {H12507
172b0 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69  } If the authori
172c0 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e  zer code (the 2n
172d0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
172e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a  he authorizer.**
172f0 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
17300 63 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67 20  ck) is anything 
17310 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
17320 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a  TE_READ], then.*
17330 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74  *          a ret
17340 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  urn of [SQLITE_I
17350 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 73  GNORE] has the s
17360 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b 53  ame effect as [S
17370 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a  QLITE_DENY]..**.
17380 2a 2a 20 7b 48 31 32 35 31 30 7d 20 54 68 65 20  ** {H12510} The 
17390 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
173a0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
173b0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
173c0 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20  copy of.**      
173d0 20 20 20 20 74 68 65 20 74 68 69 72 64 20 70 61      the third pa
173e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
173f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17400 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
17410 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  ace..**.** {H125
17420 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70  11} The second p
17430 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
17440 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
17450 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
17460 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20     [SQLITE_COPY 
17470 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
17480 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
17490 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
174a0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
174b0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
174c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 32 7d  ..**.** {H12512}
174d0 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75   The third throu
174e0 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
174f0 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ers to the callb
17500 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20 20  ack are.**      
17510 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
17520 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
17530 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20   contain.**     
17540 20 20 20 20 20 61 64 64 69 74 69 6f 6e 61 6c 20       additional 
17550 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
17560 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
17570 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
17580 20 7b 48 31 32 35 32 30 7d 20 45 61 63 68 20 63   {H12520} Each c
17590 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
175a0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
175b0 5d 20 6f 76 65 72 72 69 64 65 73 0a 2a 2a 20 20  ] overrides.**  
175c0 20 20 20 20 20 20 20 20 61 6e 79 20 70 72 65 76          any prev
175d0 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64  iously installed
175e0 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
175f0 2a 2a 20 7b 48 31 32 35 32 31 7d 20 41 20 4e 55  ** {H12521} A NU
17600 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65  LL authorizer me
17610 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68  ans that no auth
17620 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20  orization.**    
17630 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69        callback i
17640 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
17650 20 7b 48 31 32 35 32 32 7d 20 54 68 65 20 64 65   {H12522} The de
17660 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72  fault authorizer
17670 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   is NULL..*/.int
17680 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
17690 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
176a0 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
176b0 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
176c0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
176d0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
176e0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
176f0 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
17700 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
17710 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
17720 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 48   Return Codes {H
17730 31 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e 0a  12590} <H12500>.
17740 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
17750 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
17760 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
17770 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
17780 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
17790 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
177a0 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
177b0 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
177c0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
177d0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
177e0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
177f0 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
17800 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
17810 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
17820 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
17830 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
17840 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
17850 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
17860 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  tion..*/.#define
17870 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
17880 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
17890 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
178a0 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
178b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
178c0 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
178d0 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
178e0 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
178f0 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
17900 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17910 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
17920 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30 7d  n Codes {H12550}
17930 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H12500>.**.** 
17940 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
17950 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
17960 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
17970 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
17980 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
17990 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
179a0 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
179b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
179c0 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
179d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
179e0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
179f0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
17a00 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
17a10 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
17a20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
17a30 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
17a40 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
17a50 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
17a60 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
17a70 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
17a80 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
17a90 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
17aa0 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
17ab0 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
17ac0 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
17ad0 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
17ae0 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
17af0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
17b00 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
17b10 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
17b20 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
17b30 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
17b40 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
17b50 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
17b60 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
17b70 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17b80 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61  ter.  The 5th pa
17b90 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
17ba0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
17bb0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
17bc0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
17bd0 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
17be0 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
17bf0 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20  pplicable.  The 
17c00 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
17c10 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
17c20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
17c30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
17c40 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
17c50 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
17c60 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
17c70 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
17c80 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
17c90 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
17ca0 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
17cb0 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
17cc0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
17cd0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
17ce0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 31 7d 20  .**.** {H12551} 
17cf0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17d00 65 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 20  eter to an.**   
17d10 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
17d20 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
17d30 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17d40 62 61 63 6b 5d 20 69 73 20 61 6c 77 61 79 73 20  back] is always 
17d50 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20  an integer.**   
17d60 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43         [SQLITE_C
17d70 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  OPY | authorizer
17d80 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
17d90 69 66 69 65 73 20 77 68 61 74 20 61 63 74 69 6f  ifies what actio
17da0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  n.**          is
17db0 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
17dc0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 32  d..**.** {H12552
17dd0 7d 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74  } The 3rd and 4t
17de0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
17df0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
17e00 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
17e10 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
17e20 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  ization callback
17e30 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
17e40 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
17e50 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
17e60 6e 67 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 20  ng on which.**  
17e70 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
17e80 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65  COPY | authorize
17e90 72 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64 20  r code] is used 
17ea0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
17eb0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
17ec0 48 31 32 35 35 33 7d 20 54 68 65 20 35 74 68 20  H12553} The 5th 
17ed0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
17ee0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
17ef0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
17f00 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
17f10 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74  r callback] is t
17f20 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he name.**      
17f30 20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61 62      of the datab
17f40 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d  ase (example: "m
17f50 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74  ain", "temp", et
17f60 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
17f70 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 34  e..**.** {H12554
17f80 7d 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65  } The 6th parame
17f90 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ter to the.**   
17fa0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
17fb0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
17fc0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17fd0 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d  back] is the nam
17fe0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
17ff0 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
18000 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
18010 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
18020 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ble for.**      
18030 20 20 20 20 74 68 65 20 61 63 63 65 73 73 20 61      the access a
18040 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
18050 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
18060 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
18070 79 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20  y from.**       
18080 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c     top-level SQL
18090 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
180a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
180b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
180c0 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
180d0 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
180e0 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
180f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
18100 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
18110 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
18120 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
18130 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18140 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
18150 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
18160 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18170 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18180 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18190 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
181a0 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
181b0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
181c0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
181d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
181e0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
181f0 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
18200 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
18210 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18220 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18230 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
18240 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
18250 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
18260 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18270 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18280 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
18290 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
182a0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
182b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
182c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
182d0 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
182e0 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
182f0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
18300 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
18310 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18320 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
18330 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
18340 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
18350 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18370 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
18380 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
18390 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
183a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
183b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
183c0 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
183d0 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
183e0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
183f0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18400 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
18410 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
18420 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
18430 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
18440 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
18460 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
18470 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
18480 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
18490 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
184a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
184b0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
184c0 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
184d0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
184e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
184f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
18500 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
18510 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
18520 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
18530 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
18540 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
18550 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
18560 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
18570 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
18580 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18590 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
185a0 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
185b0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
185c0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
185d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
185e0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
185f0 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
18600 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
18610 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18620 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18630 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
18640 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
18650 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18660 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18670 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18680 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
18690 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
186a0 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
186b0 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
186c0 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
186d0 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
186e0 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
186f0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
18700 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
18710 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18720 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
18730 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
18740 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18750 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18760 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18770 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
18780 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
18790 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
187a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
187b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
187c0 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
187d0 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
187e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
187f0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
18800 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18810 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
18820 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
18830 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
18840 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18850 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18860 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
18870 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
18880 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
18890 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
188a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
188b0 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
188c0 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
188d0 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
188e0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
188f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
18900 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
18910 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
18920 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
18930 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18940 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
18950 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
18960 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
18970 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
18980 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18990 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
189a0 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
189b0 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
189c0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
189d0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
189e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
189f0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
18a00 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
18a10 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
18a20 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
18a30 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
18a40 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
18a50 31 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20  1   /* Function 
18a60 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
18a70 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18a80 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
18a90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
18aa0 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
18ab0 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
18ac0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
18ad0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
18ae0 75 6e 63 74 69 6f 6e 73 20 7b 48 31 32 32 38 30  unctions {H12280
18af0 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60400>.**.**
18b00 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
18b10 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
18b20 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
18b30 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
18b40 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
18b50 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
18b60 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
18b70 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
18b80 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
18b90 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
18ba0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
18bb0 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
18bc0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
18bd0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
18be0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
18bf0 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
18c00 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54  e3_step()]..** T
18c10 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
18c20 72 6e 73 20 61 20 55 54 46 2d 38 20 72 65 6e 64  rns a UTF-8 rend
18c30 65 72 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c  ering of the SQL
18c40 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 0a   statement text.
18c50 2a 2a 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  ** as the statem
18c60 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
18c70 20 65 78 65 63 75 74 69 6e 67 2e 20 20 41 64 64   executing.  Add
18c80 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b  itional callback
18c90 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  s occur.** as ea
18ca0 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
18cb0 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
18cc0 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
18cd0 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
18ce0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
18cf0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
18d00 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
18d10 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a  he trigger..**.*
18d20 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
18d30 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
18d40 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
18d50 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
18d60 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
18d70 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
18d80 73 68 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69  shes.  The profi
18d90 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
18da0 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
18db0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
18dc0 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
18dd0 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
18de0 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
18df0 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
18e00 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
18e10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
18e20 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 50  te3_profile() AP
18e30 49 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  I is currently c
18e40 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
18e50 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73  mental and.** is
18e60 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
18e70 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e  ge or removal in
18e80 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
18e90 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 72 69  e..**.** The tri
18ea0 67 67 65 72 20 72 65 70 6f 72 74 69 6e 67 20 66  gger reporting f
18eb0 65 61 74 75 72 65 20 6f 66 20 74 68 65 20 74 72  eature of the tr
18ec0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ace callback is 
18ed0 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 65 78  considered.** ex
18ee0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
18ef0 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  s subject to cha
18f00 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69  nge or removal i
18f10 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
18f20 73 2e 0a 2a 2a 20 46 75 74 75 72 65 20 76 65 72  s..** Future ver
18f30 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
18f40 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6e  might also add n
18f50 65 77 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ew trace callbac
18f60 6b 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  k.** invocations
18f70 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
18f80 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  TS:.**.** {H1228
18f90 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  1} The callback 
18fa0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
18fb0 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  red by [sqlite3_
18fc0 74 72 61 63 65 28 29 5d 20 69 73 0a 2a 2a 20 20  trace()] is.**  
18fd0 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72          whenever
18fe0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
18ff0 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74  t first begins t
19000 6f 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a  o execute and.**
19010 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76            whenev
19020 65 72 20 61 20 74 72 69 67 67 65 72 20 73 75 62  er a trigger sub
19030 70 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65  program first be
19040 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a  gins to run..**.
19050 2a 2a 20 7b 48 31 32 32 38 32 7d 20 45 61 63 68  ** {H12282} Each
19060 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
19070 33 5f 74 72 61 63 65 28 29 5d 20 6f 76 65 72 72  3_trace()] overr
19080 69 64 65 73 20 74 68 65 20 70 72 65 76 69 6f 75  ides the previou
19090 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  sly.**          
190a0 72 65 67 69 73 74 65 72 65 64 20 74 72 61 63 65  registered trace
190b0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
190c0 20 7b 48 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c   {H12283} A NULL
190d0 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
190e0 64 69 73 61 62 6c 65 73 20 74 72 61 63 69 6e 67  disables tracing
190f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 34 7d  ..**.** {H12284}
19100 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
19110 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65  ent to the trace
19120 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
19130 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  opy of.**       
19140 20 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77     the pointer w
19150 68 69 63 68 20 77 61 73 20 74 68 65 20 33 72 64  hich was the 3rd
19160 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
19170 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a  lite3_trace()]..
19180 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d 20 54  **.** {H12285} T
19190 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
191a0 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  nt to the trace 
191b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a  callback is a.**
191c0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
191d0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
191e0 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
191f0 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74  g the original t
19200 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ext.**          
19210 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  of the SQL state
19220 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70  ment as it was p
19230 61 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69  assed into [sqli
19240 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
19250 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
19260 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c   the equivalent,
19270 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65   or an SQL comme
19280 6e 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  nt indicating th
19290 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20  e beginning.**  
192a0 20 20 20 20 20 20 20 20 6f 66 20 61 20 74 72 69          of a tri
192b0 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e  gger subprogram.
192c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37 7d 20  .**.** {H12287} 
192d0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
192e0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
192f0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f   by [sqlite3_pro
19300 66 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b  file()] is invok
19310 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ed.**          a
19320 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
19330 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a  ment finishes..*
19340 2a 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20 54 68  *.** {H12288} Th
19350 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
19360 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65  r to the profile
19370 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
19380 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  opy of.**       
19390 20 20 20 74 68 65 20 33 72 64 20 70 61 72 61 6d     the 3rd param
193a0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
193b0 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a  _profile()]..**.
193c0 2a 2a 20 7b 48 31 32 32 38 39 7d 20 54 68 65 20  ** {H12289} The 
193d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
193e0 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
193f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a  callback is a.**
19400 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
19410 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
19420 73 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74  string that cont
19430 61 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74  ains the complet
19440 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20  e text of.**    
19450 20 20 20 20 20 20 74 68 65 20 53 51 4c 20 73 74        the SQL st
19460 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61  atement as it wa
19470 73 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b  s processed by [
19480 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
19490 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  v2()].**        
194a0 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c    or the equival
194b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ent..**.** {H122
194c0 39 30 7d 20 54 68 65 20 74 68 69 72 64 20 70 61  90} The third pa
194d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70  rameter to the p
194e0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
194f0 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a  is an estimate.*
19500 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
19510 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f  e number of nano
19520 73 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d  seconds of wall-
19530 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69  clock time requi
19540 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  red to.**       
19550 20 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73     run the SQL s
19560 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74  tatement from st
19570 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a  art to finish..*
19580 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
19590 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
195a0 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
195b0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
195c0 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
195d0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
195e0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
195f0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
19600 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
19610 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
19620 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
19630 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
19640 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
19650 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 34  s {H12910} <S604
19660 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
19670 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65  outine configure
19680 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
19690 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70  ction - the.** p
196a0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
196b0 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b   - that is invok
196c0 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
196d0 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72  during long.** r
196e0 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20  unning calls to 
196f0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
19700 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
19710 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
19720 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e  e3_get_table()].
19730 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
19740 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
19750 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
19760 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
19770 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
19780 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uery..**.** If t
19790 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
197a0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
197b0 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
197c0 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
197d0 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
197e0 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
197f0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
19800 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
19810 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 64 69 61  ton on a GUI dia
19820 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49  log box..**.** I
19830 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
19840 20 7b 48 31 32 39 31 31 7d 20 54 68 65 20 63 61   {H12911} The ca
19850 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
19860 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
19870 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
19880 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20  andler().**     
19890 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20       is invoked 
198a0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
198b0 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
198c0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20   calls to.**    
198d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
198e0 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tep()]..**.** {H
198f0 31 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67 72  12912} The progr
19900 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ess callback is 
19910 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
19920 20 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c   every N virtual
19930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61 63  .**          mac
19940 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68  hine opcodes, wh
19950 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
19960 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
19970 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
19980 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73  [sqlite3_progres
19990 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c  s_handler()] cal
199a0 6c 20 74 68 61 74 20 72 65 67 69 73 74 65 72 65  l that registere
199b0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  d.**          th
199c0 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20  e callback.  If 
199d0 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31  N is less than 1
199e0 2c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  , sqlite3_progre
199f0 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20  ss_handler().** 
19a00 20 20 20 20 20 20 20 20 20 61 63 74 73 20 61 73           acts as
19a10 20 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67 72   if a NULL progr
19a20 65 73 73 20 68 61 6e 64 6c 65 72 20 68 61 64 20  ess handler had 
19a30 62 65 65 6e 20 73 70 65 63 69 66 69 65 64 2e 0a  been specified..
19a40 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 33 7d 20 54  **.** {H12913} T
19a50 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
19a60 62 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20 69  back itself is i
19a70 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
19a80 20 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 20   third.**       
19a90 20 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73     argument to s
19aa0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
19ab0 68 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a 2a  handler()..**.**
19ac0 20 7b 48 31 32 39 31 34 7d 20 54 68 65 20 66 6f   {H12914} The fo
19ad0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
19ae0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
19af0 73 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20 61  s_handler() is a
19b00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 6f 69  .**          voi
19b10 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  d pointer passed
19b20 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73   to the progress
19b30 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
19b40 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 65        function e
19b50 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69  ach time it is i
19b60 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nvoked..**.** {H
19b70 31 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c 6c  12915} If a call
19b80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
19b90 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e 20  p()] results in 
19ba0 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 63  fewer than N opc
19bb0 6f 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  odes.**         
19bc0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c   being executed,
19bd0 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
19be0 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ss callback is n
19bf0 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  ever invoked..**
19c00 0a 2a 2a 20 7b 48 31 32 39 31 36 7d 20 45 76 65  .** {H12916} Eve
19c10 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ry call to [sqli
19c20 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
19c30 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20  dler()].**      
19c40 20 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 61      overwrites a
19c50 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ny previously re
19c60 67 69 73 74 65 72 65 64 20 70 72 6f 67 72 65 73  gistered progres
19c70 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  s handler..**.**
19c80 20 7b 48 31 32 39 31 37 7d 20 49 66 20 74 68 65   {H12917} If the
19c90 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
19ca0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  r callback is NU
19cb0 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72  LL then no progr
19cc0 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ess.**          
19cd0 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b  handler is invok
19ce0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  ed..**.** {H1291
19cf0 38 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  8} If the progre
19d00 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
19d10 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68  rns a result oth
19d20 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a  er than 0, then.
19d30 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
19d40 62 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 66  behavior is a if
19d50 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
19d60 75 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20  upt()] had been 
19d70 63 61 6c 6c 65 64 2e 0a 2a 2a 20 20 20 20 20 20  called..**      
19d80 20 20 20 20 3c 53 33 30 35 30 30 3e 0a 2a 2f 0a      <S30500>.*/.
19d90 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
19da0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
19db0 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
19dc0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
19dd0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
19de0 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
19df0 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
19e00 65 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d 20  ection {H12700} 
19e10 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S40200>.**.** T
19e20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
19e30 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
19e40 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65  abase file whose
19e50 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62   name is given b
19e60 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  y the.** filenam
19e70 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20  e argument. The 
19e80 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
19e90 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
19ea0 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
19eb0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
19ec0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
19ed0 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
19ee0 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
19ef0 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
19f00 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
19f10 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61 73  16(). A [databas
19f20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
19f30 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
19f40 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
19f50 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
19f60 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
19f70 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
19f80 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
19f90 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
19fa0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
19fb0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
19fc0 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
19fd0 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
19fe0 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
19ff0 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
1a000 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
1a010 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
1a020 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65 20   object. If the 
1a030 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1a040 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
1a050 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
1a060 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
1a070 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
1a080 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
1a090 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
1a0a0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a   returned.  The.
1a0b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1a0c0 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
1a0d0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
1a0e0 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
1a0f0 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
1a100 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
1a110 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
1a120 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  of the error..**
1a130 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
1a140 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
1a150 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1a160 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71  e UTF-8 if.** sq
1a170 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1a180 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1a190 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ) is called and.
1a1a0 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  ** UTF-16 in the
1a1b0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1a1c0 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70  er if sqlite3_op
1a1d0 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a  en16() is used..
1a1e0 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
1a1f0 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
1a200 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
1a210 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
1a220 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
1a230 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
1a240 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1a250 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
1a260 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
1a270 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
1a280 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
1a290 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
1a2a0 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
1a2b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1a2c0 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
1a2d0 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
1a2e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
1a2f0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1a300 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
1a310 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
1a320 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
1a330 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
1a340 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
1a350 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  e connection.  T
1a360 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
1a370 65 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  er can take one 
1a380 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
1a390 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
1a3a0 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
1a3b0 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
1a3c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1a3d0 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 3a 0a 2a  NOMUTEX] flag:.*
1a3e0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
1a3f0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1a400 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
1a410 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1a420 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
1a430 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
1a440 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
1a450 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
1a460 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
1a470 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
1a480 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b  /dd>.**.** <dt>[
1a490 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1a4a0 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
1a4b0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1a4c0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1a4d0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1a4e0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
1a4f0 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
1a500 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
1a510 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
1a520 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
1a530 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
1a540 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
1a550 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
1a560 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
1a570 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
1a580 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1a590 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51  d>.**.** <dt>[SQ
1a5a0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1a5b0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
1a5c0 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
1a5d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1a5e0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1a5f0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
1a600 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
1a610 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20  reates it if.** 
1a620 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
1a630 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
1a640 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
1a650 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
1a660 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
1a670 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1a680 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
1a690 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  /dd>.** </dl>.**
1a6a0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
1a6b0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1a6c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1a6d0 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
1a6e0 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
1a6f0 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f  shown above or o
1a700 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e  ne of the combin
1a710 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1a720 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77  ve combined.** w
1a730 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
1a740 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
1a750 61 67 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ag, then the beh
1a760 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
1a770 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
1a780 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1a790 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1a7a0 65 74 2c 20 74 68 65 6e 20 6d 75 74 65 78 65 73  et, then mutexes
1a7b0 20 6f 6e 20 74 68 65 0a 2a 2a 20 6f 70 65 6e 65   on the.** opene
1a7c0 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  d [database conn
1a7d0 65 63 74 69 6f 6e 5d 20 61 72 65 20 64 69 73 61  ection] are disa
1a7e0 62 6c 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  bled and the app
1a7f0 6c 69 61 74 69 6f 6e 20 6d 75 73 74 0a 2a 2a 20  liation must.** 
1a800 69 6e 73 75 72 65 20 74 68 61 74 20 61 63 63 65  insure that acce
1a810 73 73 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  ss to the [datab
1a820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1a830 61 6e 64 20 69 74 73 20 61 73 73 6f 63 69 61 74  and its associat
1a840 65 64 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  ed.** [prepared 
1a850 73 74 61 74 65 6d 65 6e 74 73 5d 20 69 73 20 73  statements] is s
1a860 65 72 69 61 6c 69 7a 65 64 2e 20 20 54 68 65 20  erialized.  The 
1a870 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1a880 55 54 45 58 5d 20 66 6c 61 67 0a 2a 2a 20 69 73  UTEX] flag.** is
1a890 20 74 68 65 20 64 65 66 61 75 6c 74 20 62 65 68   the default beh
1a8a0 61 76 69 6f 72 20 69 73 20 53 51 4c 69 74 65 20  avior is SQLite 
1a8b0 69 73 20 63 6f 6e 66 69 67 75 72 65 64 20 75 73  is configured us
1a8c0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
1a8d0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
1a8e0 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
1a8f0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
1a900 48 52 45 41 44 5d 20 6f 70 74 69 6f 6e 73 0a 2a  HREAD] options.*
1a910 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  * to [sqlite3_co
1a920 6e 66 69 67 28 29 5d 2e 20 20 54 68 65 20 5b 53  nfig()].  The [S
1a930 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1a940 45 58 5d 20 66 6c 61 67 20 6f 6e 6c 79 20 6d 61  EX] flag only ma
1a950 6b 65 73 20 61 0a 2a 2a 20 64 69 66 66 65 72 65  kes a.** differe
1a960 6e 63 65 20 77 68 65 6e 20 53 51 4c 69 74 65 20  nce when SQLite 
1a970 69 73 20 69 6e 20 69 74 73 20 64 65 66 61 75 6c  is in its defaul
1a980 74 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  t [SQLITE_CONFIG
1a990 5f 53 45 52 49 41 4c 49 5a 45 44 5d 20 6d 6f 64  _SERIALIZED] mod
1a9a0 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
1a9b0 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
1a9c0 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
1a9d0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
1a9e0 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
1a9f0 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
1aa00 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
1aa10 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d  ction.  This in-
1aa20 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
1aa30 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
1aa40 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1aa50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1aa60 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
1aa70 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1aa80 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
1aa90 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
1aaa0 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
1aab0 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
1aac0 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
1aad0 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
1aae0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
1aaf0 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
1ab00 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
1ab10 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
1ab20 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
1ab30 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
1ab40 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
1ab50 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
1ab60 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
1ab70 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
1ab80 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49  biguity..**.** I
1ab90 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1aba0 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
1abb0 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
1abc0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
1abd0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
1abe0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
1abf0 2e 20 20 54 68 69 73 20 70 72 69 76 61 74 65 20  .  This private 
1ac00 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1ac10 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1ac20 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
1ac30 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
1ac40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1ac50 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
1ac60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1ac70 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1ac80 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
1ac90 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
1aca0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1acb0 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
1acc0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1acd0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
1ace0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
1acf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ad00 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
1ad10 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
1ad20 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
1ad30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1ad40 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
1ad50 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1ad60 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
1ad70 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
1ad80 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
1ad90 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
1ada0 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
1adb0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
1adc0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
1add0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
1ade0 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
1adf0 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
1ae00 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
1ae10 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
1ae20 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
1ae30 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
1ae40 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
1ae50 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
1ae60 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
1ae70 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
1ae80 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
1ae90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1aea0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
1aeb0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  v2()..**.** INVA
1aec0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
1aed0 31 32 37 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  12701} The [sqli
1aee0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1aef0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
1af00 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
1af10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1af20 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
1af30 63 72 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20  create a new.** 
1af40 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
1af50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1af60 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
1af70 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 64  *          the d
1af80 61 74 61 62 61 73 65 20 66 69 6c 65 20 67 69 76  atabase file giv
1af90 65 6e 20 69 6e 20 74 68 65 69 72 20 66 69 72 73  en in their firs
1afa0 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  t parameter..**.
1afb0 2a 2a 20 7b 48 31 32 37 30 32 7d 20 54 68 65 20  ** {H12702} The 
1afc0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1afd0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
1afe0 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20   as UTF-8.**    
1aff0 20 20 20 20 20 20 66 6f 72 20 5b 73 71 6c 69 74        for [sqlit
1b000 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b  e3_open()] and [
1b010 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1b020 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  )] and as UTF-16
1b030 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
1b040 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
1b050 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74  order for [sqlit
1b060 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
1b070 0a 2a 2a 20 7b 48 31 32 37 30 33 7d 20 41 20 73  .** {H12703} A s
1b080 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
1b090 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1b0a0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1b0b0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
1b0c0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
1b0d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1b0e0 20 77 72 69 74 65 73 20 61 20 70 6f 69 6e 74 65   writes a pointe
1b0f0 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20  r to a new.**   
1b100 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
1b110 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74   connection] int
1b120 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b  o *ppDb..**.** {
1b130 48 31 32 37 30 34 7d 20 54 68 65 20 5b 73 71 6c  H12704} The [sql
1b140 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1b150 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1b160 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  , and.**        
1b170 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f    [sqlite3_open_
1b180 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1b190 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1b1a0 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65 73 73  OK] upon success
1b1b0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
1b1c0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
1b1d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20  [error code] on 
1b1e0 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b  failure..**.** {
1b1f0 48 31 32 37 30 36 7d 20 54 68 65 20 64 65 66 61  H12706} The defa
1b200 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  ult text encodin
1b210 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61  g for a new data
1b220 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69  base created usi
1b230 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
1b240 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
1b250 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
1b260 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62 65 20 55  _v2()] will be U
1b270 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  TF-8..**.** {H12
1b280 37 30 37 7d 20 54 68 65 20 64 65 66 61 75 6c 74  707} The default
1b290 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66   text encoding f
1b2a0 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73  or a new databas
1b2b0 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  e created using.
1b2c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1b2d0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77  ite3_open16()] w
1b2e0 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a  ill be UTF-16..*
1b2f0 2a 0a 2a 2a 20 7b 48 31 32 37 30 39 7d 20 54 68  *.** {H12709} Th
1b300 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
1b310 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,D)] interface 
1b320 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
1b330 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1b340 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
1b350 44 2c 47 2c 30 29 5d 20 77 68 65 72 65 20 74 68  D,G,0)] where th
1b360 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 69 73  e G parameter is
1b370 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
1b380 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1b390 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45  ITE]|[SQLITE_OPE
1b3a0 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a  N_CREATE]..**.**
1b3b0 20 7b 48 31 32 37 31 31 7d 20 49 66 20 74 68 65   {H12711} If the
1b3c0 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
1b3d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1b3e0 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61  (F,D,G,V)] conta
1b3f0 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ins the.**      
1b400 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
1b410 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1b420 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65 20 64 61  NLY] then the da
1b430 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1b440 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
1b450 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a   reading only..*
1b460 2a 0a 2a 2a 20 7b 48 31 32 37 31 32 7d 20 49 66  *.** {H12712} If
1b470 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
1b480 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
1b490 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63  n_v2(F,D,G,V)] c
1b4a0 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20  ontains the.**  
1b4b0 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
1b4c0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
1b4d0 45 41 44 57 52 49 54 45 5d 20 74 68 65 6e 20 74  EADWRITE] then t
1b4e0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1b4f0 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  pened.**        
1b500 20 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72    reading and wr
1b510 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
1b520 65 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69 6e  e, or for readin
1b530 67 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a  g only if the.**
1b540 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 20 69            file i
1b550 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
1b560 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
1b570 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  ng system..**.**
1b580 20 7b 48 31 32 37 31 33 7d 20 49 66 20 74 68 65   {H12713} If the
1b590 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
1b5a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32  [sqlite3_open(v2
1b5b0 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73  (F,D,G,V)] omits
1b5c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1b5d0 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49   bit value [SQLI
1b5e0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
1b5f0 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
1b600 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20   does not.**    
1b610 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79        previously
1b620 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
1b630 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1b640 0a 2a 2a 20 7b 48 31 32 37 31 34 7d 20 49 66 20  .** {H12714} If 
1b650 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
1b660 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1b670 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f  (v2(F,D,G,V)] co
1b680 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20  ntains the.**   
1b690 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65         bit value
1b6a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
1b6b0 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61  EATE] and the da
1b6c0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
1b6d0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76  **          prev
1b6e0 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 74 68  iously exist, th
1b6f0 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  en an attempt is
1b700 20 6d 61 64 65 20 74 6f 20 63 72 65 61 74 65 20   made to create 
1b710 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
1b720 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 64  initialize the d
1b730 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b  atabase..**.** {
1b740 48 31 32 37 31 37 7d 20 49 66 20 74 68 65 20 66  H12717} If the f
1b750 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1b760 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
1b770 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
1b780 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20  pen16()],.**    
1b790 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
1b7a0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20  3_open_v2()] is 
1b7b0 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
1b7c0 20 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20   an private,.** 
1b7d0 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72           ephemer
1b7e0 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  al, in-memory da
1b7f0 74 61 62 61 73 65 20 69 73 20 63 72 65 61 74 65  tabase is create
1b800 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
1b810 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20  tion..**        
1b820 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54    <todo>Is SQLIT
1b830 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51  E_OPEN_CREATE|SQ
1b840 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1b850 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20  ITE required.** 
1b860 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69           in sqli
1b870 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f  te3_open_v2()?</
1b880 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  todo>.**.** {H12
1b890 37 31 39 7d 20 49 66 20 74 68 65 20 66 69 6c 65  719} If the file
1b8a0 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20  name is NULL or 
1b8b0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
1b8c0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1b8d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68  .**          eph
1b8e0 65 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64  emeral on-disk d
1b8f0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1b900 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20  created..**     
1b910 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51       <todo>Is SQ
1b920 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1b930 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  |SQLITE_OPEN_REA
1b940 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a  DWRITE required.
1b950 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73  **          in s
1b960 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b970 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b  ?</todo>.**.** {
1b980 48 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61 74  H12721} The [dat
1b990 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b9a0 5d 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71  ] created by [sq
1b9b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
1b9c0 44 2c 47 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 20  D,G,V)].**      
1b9d0 20 20 20 20 77 69 6c 6c 20 75 73 65 20 74 68 65      will use the
1b9e0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1b9f0 62 6a 65 63 74 20 69 64 65 6e 74 69 66 69 65 64  bject identified
1ba00 20 62 79 20 74 68 65 20 56 20 70 61 72 61 6d 65   by the V parame
1ba10 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ter,.**         
1ba20 20 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20   or the default 
1ba30 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1ba40 6a 65 63 74 20 69 66 20 56 20 69 73 20 61 20 4e  ject if V is a N
1ba50 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1ba60 2a 2a 20 7b 48 31 32 37 32 33 7d 20 54 77 6f 20  ** {H12723} Two 
1ba70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ba80 74 69 6f 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72  tions] will shar
1ba90 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65  e a common cache
1baa0 20 69 66 20 62 6f 74 68 20 77 65 72 65 0a 2a 2a   if both were.**
1bab0 20 20 20 20 20 20 20 20 20 20 6f 70 65 6e 65 64            opened
1bac0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 56   with the same V
1bad0 46 53 20 77 68 69 6c 65 20 5b 73 68 61 72 65 64  FS while [shared
1bae0 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 77 61 73   cache mode] was
1baf0 20 65 6e 61 62 6c 65 64 20 61 6e 64 0a 2a 2a 20   enabled and.** 
1bb00 20 20 20 20 20 20 20 20 20 69 66 20 62 6f 74 68           if both
1bb10 20 66 69 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61   filenames compa
1bb20 72 65 20 65 71 75 61 6c 20 75 73 69 6e 67 20 6d  re equal using m
1bb30 65 6d 63 6d 70 28 29 20 61 66 74 65 72 20 68 61  emcmp() after ha
1bb40 76 69 6e 67 20 62 65 65 6e 0a 2a 2a 20 20 20 20  ving been.**    
1bb50 20 20 20 20 20 20 70 72 6f 63 65 73 73 65 64 20        processed 
1bb60 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
1bb70 76 66 73 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e  vfs | xFullPathn
1bb80 61 6d 65 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74  ame] method of t
1bb90 68 65 20 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73  he VFS..*/.int s
1bba0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
1bbb0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
1bbc0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1bbd0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1bbe0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
1bbf0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
1bc00 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1bc10 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
1bc20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1bc30 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
1bc40 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1bc50 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1bc60 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
1bc70 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
1bc80 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1bc90 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1bca0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
1bcb0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
1bcc0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
1bcd0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1bce0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1bcf0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
1bd00 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
1bd10 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1bd20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
1bd30 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
1bd40 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
1bd50 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1bd60 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
1bd70 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
1bd80 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
1bd90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1bda0 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
1bdb0 20 4d 65 73 73 61 67 65 73 20 7b 48 31 32 38 30   Messages {H1280
1bdc0 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a  0} <S60200>.**.*
1bdd0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72  * The sqlite3_er
1bde0 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
1bdf0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1be00 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
1be10 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
1be20 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
1be30 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
1be40 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
1be50 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
1be60 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1be70 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
1be80 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
1be90 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
1bea0 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
1beb0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
1bec0 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
1bed0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1bee0 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
1bef0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
1bf00 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
1bf10 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
1bf20 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
1bf30 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
1bf40 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
1bf50 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
1bf60 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
1bf70 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
1bf80 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
1bf90 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
1bfa0 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   Memory to hold 
1bfb0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
1bfc0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
1bfd0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
1bfe0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1bff0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
1c000 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
1c010 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
1c020 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
1c030 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
1c040 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
1c050 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
1c060 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
1c070 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
1c080 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
1c090 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
1c0a0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
1c0b0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
1c0c0 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
1c0d0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
1c0e0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
1c0f0 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
1c100 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
1c110 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
1c120 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
1c130 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
1c140 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
1c150 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   not be set..**.
1c160 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1c170 2a 0a 2a 2a 20 7b 48 31 32 38 30 31 7d 20 54 68  *.** {H12801} Th
1c180 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  e [sqlite3_errco
1c190 64 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65  de(D)] interface
1c1a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1c1b0 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20  eric.**         
1c1c0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
1c1d0 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  r [extended resu
1c1e0 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
1c1f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a   most recently.*
1c200 2a 20 20 20 20 20 20 20 20 20 20 66 61 69 6c 65  *          faile
1c210 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  d interface call
1c220 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1c230 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1c240 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
1c250 0a 2a 2a 20 7b 48 31 32 38 30 33 7d 20 54 68 65  .** {H12803} The
1c260 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1c270 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  (D)] and [sqlite
1c280 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a  3_errmsg16(D)].*
1c290 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
1c2a0 66 61 63 65 73 20 72 65 74 75 72 6e 20 45 6e 67  faces return Eng
1c2b0 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65  lish-language te
1c2c0 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
1c2d0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
1c2e0 65 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d  e error in the m
1c2f0 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66  ostly recently f
1c300 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20  ailed interface 
1c310 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20  call,.**        
1c320 20 20 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74    encoded as eit
1c330 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
1c340 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
1c350 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 37 7d  ..**.** {H12807}
1c360 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1c370 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1c380 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20  3_errmsg()] and 
1c390 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1c3a0 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  6()].**         
1c3b0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
1c3c0 20 74 68 65 20 6e 65 78 74 20 53 51 4c 69 74 65   the next SQLite
1c3d0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2e   interface call.
1c3e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 38 7d 20  .**.** {H12808} 
1c3f0 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75  Calls to API rou
1c400 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  tines that do no
1c410 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  t return an erro
1c420 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
1c430 20 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71     (example: [sq
1c440 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
1c450 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20  ()]) do not.**  
1c460 20 20 20 20 20 20 20 20 63 68 61 6e 67 65 20 74          change t
1c470 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 72  he error code or
1c480 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e 65   message returne
1c490 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
1c4a0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1c4b0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65  e()], [sqlite3_e
1c4c0 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71  rrmsg()], or [sq
1c4d0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1c4e0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 39  ]..**.** {H12809
1c4f0 7d 20 49 6e 74 65 72 66 61 63 65 73 20 74 68 61  } Interfaces tha
1c500 74 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 69  t are not associ
1c510 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65 63  ated with a spec
1c520 69 66 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20  ific.**         
1c530 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c540 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73  ction] (examples
1c550 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  :.**          [s
1c560 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1c570 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e  ] or [sqlite3_en
1c580 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
1c590 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  e()].**         
1c5a0 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20 74   do not change t
1c5b0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1c5c0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1c5d0 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f    [sqlite3_errco
1c5e0 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
1c5f0 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73  errmsg()], or [s
1c600 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1c610 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1c620 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
1c630 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
1c640 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
1c650 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
1c660 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1c670 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
1c680 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1c690 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
1c6a0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31  ement Object {H1
1c6b0 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a  3000} <H13010>.*
1c6c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
1c6d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
1c6e0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1c6f0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
1c700 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
1c710 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
1c720 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
1c730 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
1c740 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
1c750 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
1c760 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
1c770 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
1c780 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
1c790 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
1c7a0 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
1c7b0 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
1c7c0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
1c7d0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
1c7e0 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
1c7f0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
1c800 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
1c810 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1c820 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1c830 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
1c840 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
1c850 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
1c860 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
1c870 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
1c880 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
1c890 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
1c8a0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
1c8b0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
1c8c0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
1c8d0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
1c8e0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
1c8f0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
1c900 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1c910 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1c920 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
1c930 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
1c940 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
1c950 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1c960 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
1c970 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1c980 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1c990 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
1c9a0 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
1c9b0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
1c9c0 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
1c9d0 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
1c9e0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1c9f0 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
1ca00 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1ca10 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
1ca20 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
1ca30 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
1ca40 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c  imits {H12760} <
1ca50 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20600>.**.** Th
1ca60 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1ca70 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
1ca80 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
1ca90 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
1caa0 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
1cab0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
1cac0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
1cad0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
1cae0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
1caf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
1cb00 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
1cb10 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
1cb20 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
1cb30 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
1cb40 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
1cb50 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
1cb60 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
1cb70 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
1cb80 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
1cb90 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
1cba0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1cbb0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
1cbc0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
1cbd0 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e  t.  The function
1cbe0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64   returns the old
1cbf0 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66   limit..**.** If
1cc00 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
1cc10 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
1cc20 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
1cc30 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
1cc40 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61  For the limit ca
1cc50 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45  tegory of SQLITE
1cc60 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65  _LIMIT_XYZ there
1cc70 20 69 73 20 61 20 68 61 72 64 20 75 70 70 65 72   is a hard upper
1cc80 0a 2a 2a 20 62 6f 75 6e 64 20 73 65 74 20 62 79  .** bound set by
1cc90 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20   a compile-time 
1cca0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1ccb0 61 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54  acro named SQLIT
1ccc0 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54  E_MAX_XYZ..** (T
1ccd0 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
1cce0 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
1ccf0 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
1cd00 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20  .** Attempts to 
1cd10 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
1cd20 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
1cd30 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
1cd40 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
1cd50 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
1cd60 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a  d upper limit..*
1cd70 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69  *.** Run time li
1cd80 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
1cd90 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
1cda0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
1cdb0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
1cdc0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
1cdd0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
1cde0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
1cdf0 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
1ce00 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
1ce10 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
1ce20 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
1ce30 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
1ce40 20 62 65 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77   be a.** webbrow
1ce50 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
1ce60 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
1ce70 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
1ce80 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
1ce90 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
1cea0 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
1ceb0 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
1cec0 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
1ced0 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
1cee0 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
1cef0 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
1cf00 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
1cf10 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
1cf20 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
1cf30 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
1cf40 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
1cf50 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
1cf60 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
1cf70 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
1cf80 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
1cf90 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
1cfa0 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
1cfb0 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
1cfc0 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
1cfd0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1cfe0 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
1cff0 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
1d000 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
1d010 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
1d020 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
1d030 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
1d040 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
1d050 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
1d060 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
1d070 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
1d080 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
1d090 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
1d0a0 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
1d0b0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
1d0c0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
1d0d0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1d0e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 32 7d 20  .**.** {H12762} 
1d0f0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
1d100 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69  l to [sqlite3_li
1d110 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72  mit(D,C,V)] wher
1d120 65 20 56 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  e V is.**       
1d130 20 20 20 70 6f 73 69 74 69 76 65 20 63 68 61 6e     positive chan
1d140 67 65 73 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e  ges the limit on
1d150 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e   the size of con
1d160 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a  struct C in the.
1d170 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
1d180 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d190 5d 20 44 20 74 6f 20 74 68 65 20 6c 65 73 73 65  ] D to the lesse
1d1a0 72 20 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68  r of V and the h
1d1b0 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 20 20 20  ard upper.**    
1d1c0 20 20 20 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74        bound on t
1d1d0 68 65 20 73 69 7a 65 20 6f 66 20 43 20 74 68 61  he size of C tha
1d1e0 74 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70  t is set at comp
1d1f0 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ile-time..**.** 
1d200 7b 48 31 32 37 36 36 7d 20 41 20 73 75 63 63 65  {H12766} A succe
1d210 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
1d220 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43  qlite3_limit(D,C
1d230 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 20  ,V)] where V is 
1d240 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
1d250 20 20 20 20 20 6c 65 61 76 65 73 20 74 68 65 20       leaves the 
1d260 73 74 61 74 65 20 6f 66 20 74 68 65 20 5b 64 61  state of the [da
1d270 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d280 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a  n] D unchanged..
1d290 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 39 7d 20 41  **.** {H12769} A
1d2a0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
1d2b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   to [sqlite3_lim
1d2c0 69 74 28 44 2c 43 2c 56 29 5d 20 72 65 74 75 72  it(D,C,V)] retur
1d2d0 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
1d2e0 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
1d2f0 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a  limit on the siz
1d300 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43  e of construct C
1d310 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
1d320 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
1d330 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73 20 69  nnection] D as i
1d340 74 20 77 61 73 20 70 72 69 6f 72 20 74 6f 20 74  t was prior to t
1d350 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20  he call..*/.int 
1d360 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
1d370 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
1d380 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
1d390 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1d3a0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
1d3b0 65 67 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d  egories {H12790}
1d3c0 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59   <H12760>.** KEY
1d3d0 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
1d3e0 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63  tegory} {limit c
1d3f0 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
1d400 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
1d410 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
1d420 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b 64 61  aspects of a [da
1d430 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d440 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  n].** that can b
1d450 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 69 7a  e limited in siz
1d460 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73  e by calls to [s
1d470 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
1d480 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 73  .** The meanings
1d490 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
1d4a0 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20 66 6f  limits are as fo
1d4b0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c  llows:.**.** <dl
1d4c0 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
1d4d0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
1d4e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1d4f0 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
1d500 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
1d510 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64  or table row.<dd
1d520 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1d530 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
1d540 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1d550 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
1d560 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
1d570 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  tement.</dd>.**.
1d580 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1d590 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
1d5a0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1d5b0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
1d5c0 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
1d5d0 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
1d5e0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
1d5f0 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 6f  et of a SELECT o
1d600 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
1d610 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1d620 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
1d630 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
1d640 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
1d650 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  use.</dd>.**.** 
1d660 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d670 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
1d680 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1d690 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
1d6a0 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
1d6b0 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
1d6c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1d6d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
1d6e0 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
1d6f0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1d700 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
1d710 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
1d720 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1d730 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
1d740 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
1d750 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
1d760 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1d770 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
1d780 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
1d790 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
1d7a0 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
1d7b0 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
1d7c0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
1d7d0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1d7e0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
1d7f0 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
1d800 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1d810 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
1d820 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
1d830 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1d840 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
1d850 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
1d860 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1d870 72 20 6f 66 20 61 74 74 61 63 68 65 64 20 64 61  r of attached da
1d880 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a  tabases.</dd>.**
1d890 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1d8a0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
1d8b0 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
1d8c0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1d8d0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
1d8e0 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
1d8f0 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a  to the LIKE or.*
1d900 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73  * GLOB operators
1d910 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1d920 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
1d930 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
1d940 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d950 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1d960 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20  variables in an 
1d970 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
1d980 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75  at can.** be bou
1d990 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  nd.</dd>.** </dl
1d9a0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
1d9b0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
1d9c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d9d0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
1d9e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
1d9f0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
1da00 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
1da10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
1da20 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
1da30 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
1da40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
1da50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
1da60 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
1da70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1da80 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
1da90 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
1daa0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
1dab0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
1dac0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
1dad0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1dae0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
1daf0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
1db00 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1db10 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
1db20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
1db30 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1db40 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1db50 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
1db60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1db70 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1db80 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a  ER           9..
1db90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1dba0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
1dbb0 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30   Statement {H130
1dbc0 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20  10} <S10000>.** 
1dbd0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
1dbe0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
1dbf0 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
1dc00 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
1dc10 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
1dc20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
1dc30 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
1dc40 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
1dc50 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
1dc60 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
1dc70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
1dc80 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
1dc90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1dca0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
1dcb0 2a 2a 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f  ** prior call to
1dcc0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1dcd0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1dce0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
1dcf0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
1dd00 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
1dd10 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
1dd20 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
1dd30 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
1dd40 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
1dd50 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1dd60 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
1dd70 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
1dd80 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1dd90 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
1dda0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
1ddb0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1ddc0 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
1ddd0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1dde0 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
1ddf0 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  6..**.** If the 
1de00 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
1de10 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
1de20 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
1de30 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
1de40 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
1de50 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65  inator. If nByte
1de60 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
1de70 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
1de80 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
1de90 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
1dea0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68  d from zSql.  Wh
1deb0 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
1dec0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
1ded0 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
1dee0 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
1def0 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
1df00 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
1df10 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
1df20 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
1df30 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
1df40 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
1df50 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
1df60 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
1df70 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
1df80 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
1df90 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
1dfa0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
1dfb0 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
1dfc0 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
1dfd0 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
1dfe0 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
1dff0 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
1e000 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
1e010 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
1e020 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
1e030 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
1e040 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20  or bytes..**.** 
1e050 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
1e060 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
1e070 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20  first byte past 
1e080 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a  the end of the.*
1e090 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  * first SQL stat
1e0a0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
1e0b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1e0c0 6e 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  nly compile the 
1e0d0 66 69 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65  first.** stateme
1e0e0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
1e0f0 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
1e100 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20  ointing to what 
1e110 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d  remains.** uncom
1e120 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70  piled..**.** *pp
1e130 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
1e140 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
1e150 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
1e160 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
1e170 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
1e180 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1e190 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65  step()].  If the
1e1a0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
1e1b0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
1e1c0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74  * to NULL.  If t
1e1d0 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
1e1e0 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
1e1f0 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
1e200 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
1e210 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
1e220 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
1e230 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
1e240 7b 41 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c  {A13018} The cal
1e250 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
1e260 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1e270 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
1e280 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
1e290 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
1e2a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1e2b0 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
1e2c0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
1e2d0 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63  t..**.** On succ
1e2e0 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
1e2f0 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74   is returned, ot
1e300 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
1e310 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
1e320 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
1e330 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e340 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
1e350 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
1e360 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
1e370 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
1e380 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
1e390 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
1e3a0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
1e3b0 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
1e3c0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1e3d0 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
1e3e0 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
1e3f0 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65  raged..** In the
1e400 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
1e410 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
1e420 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
1e430 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
1e440 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
1e450 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
1e460 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
1e470 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
1e480 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
1e490 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
1e4a0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
1e4b0 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20   to.** behave a 
1e4c0 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
1e4d0 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  wo ways:.**.** <
1e4e0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49  ol>.** <li>.** I
1e4f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
1e500 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
1e510 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
1e520 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
1e530 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
1e540 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
1e550 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e560 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
1e570 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
1e580 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
1e590 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
1e5a0 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20  n it again.  If 
1e5b0 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63  the schema has c
1e5c0 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77  hanged in.** a w
1e5d0 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  ay that makes th
1e5e0 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c  e statement no l
1e5f0 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71  onger valid, [sq
1e600 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1e610 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75  ll still.** retu
1e620 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  rn [SQLITE_SCHEM
1e630 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20  A].  But unlike 
1e640 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
1e650 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  ior, [SQLITE_SCH
1e660 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61  EMA] is.** now a
1e670 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43   fatal error.  C
1e680 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1e690 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67  prepare_v2()] ag
1e6a0 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b  ain will not mak
1e6b0 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67  e the.** error g
1e6c0 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75  o away.  Note: u
1e6d0 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  se [sqlite3_errm
1e6e0 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68  sg()] to find th
1e6f0 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65  e text.** of the
1e700 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74   parsing error t
1e710 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61  hat results in a
1e720 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
1e730 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c  ] return..** </l
1e740 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
1e750 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f   When an error o
1e760 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
1e770 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
1e780 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
1e790 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
1e7a0 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
1e7b0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
1e7c0 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20  s].  The legacy 
1e7d0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
1e7e0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
1e7f0 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
1e800 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
1e810 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
1e820 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
1e830 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61  and you would ha
1e840 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
1e850 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
1e860 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e  ite3_reset()] in
1e870 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e   order.** to fin
1e880 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
1e890 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
1e8a0 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
1e8b0 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
1e8c0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
1e8d0 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
1e8e0 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
1e8f0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
1e900 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
1e910 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ol>.**.**
1e920 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1e930 2a 2a 20 7b 48 31 33 30 31 31 7d 20 54 68 65 20  ** {H13011} The 
1e940 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e950 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61  (db,zSql,...)] a
1e960 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
1e970 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e980 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  v2(db,zSql,...)]
1e990 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65   interfaces inte
1e9a0 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20  rpret the.**    
1e9b0 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68        text in th
1e9c0 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74  eir zSql paramet
1e9d0 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a  er as UTF-8..**.
1e9e0 2a 2a 20 7b 48 31 33 30 31 32 7d 20 54 68 65 20  ** {H13012} The 
1e9f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ea00 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  16(db,zSql,...)]
1ea10 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
1ea20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ea30 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e  e16_v2(db,zSql,.
1ea40 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  ..)] interfaces 
1ea50 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
1ea60 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69            text i
1ea70 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72  n their zSql par
1ea80 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 31 36  ameter as UTF-16
1ea90 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1eaa0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
1eab0 20 7b 48 31 33 30 31 33 7d 20 49 66 20 74 68 65   {H13013} If the
1eac0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
1ead0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
1eae0 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e  are_v2(db,zSql,n
1eaf0 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  Byte,...)].**   
1eb00 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76         and its v
1eb10 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73 73 20  ariants is less 
1eb20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53  than zero, the S
1eb30 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20 20 20  QL text is.**   
1eb40 20 20 20 20 20 20 20 72 65 61 64 20 66 72 6f 6d         read from
1eb50 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
1eb60 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
1eb70 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
1eb80 2a 0a 2a 2a 20 7b 48 31 33 30 31 34 7d 20 49 66  *.** {H13014} If
1eb90 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
1eba0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
1ebb0 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
1ebc0 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a  ql,nByte,...)].*
1ebd0 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 69  *          and i
1ebe0 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 6e  ts variants is n
1ebf0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1ec00 6e 20 61 74 20 6d 6f 73 74 20 6e 42 79 74 65 73  n at most nBytes
1ec10 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20   bytes of.**    
1ec20 20 20 20 20 20 20 53 51 4c 20 74 65 78 74 20 69        SQL text i
1ec30 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
1ec40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d  ..**.** {H13015}
1ec50 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   In [sqlite3_pre
1ec60 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
1ec70 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64  N,P,pzTail)] and
1ec80 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a   its variants.**
1ec90 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68 65            if the
1eca0 20 7a 53 71 6c 20 69 6e 70 75 74 20 74 65 78 74   zSql input text
1ecb0 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74   contains more t
1ecc0 68 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61 74  han one SQL stat
1ecd0 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  ement.**        
1ece0 20 20 61 6e 64 20 70 7a 54 61 69 6c 20 69 73 20    and pzTail is 
1ecf0 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a  not NULL, then *
1ed00 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
1ed10 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a  o point to the.*
1ed20 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74  *          first
1ed30 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65   byte past the e
1ed40 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
1ed50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1ed60 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20   zSql..**       
1ed70 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f     <todo>What do
1ed80 65 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74  es *pzTail point
1ed90 20 74 6f 20 69 66 20 74 68 65 72 65 20 69 73 20   to if there is 
1eda0 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f  one statement?</
1edb0 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  todo>.**.** {H13
1edc0 30 31 36 7d 20 41 20 73 75 63 63 65 73 73 66 75  016} A successfu
1edd0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
1ede0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
1edf0 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e  ,zSql,N,ppStmt,.
1ee00 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
1ee10 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
1ee20 61 72 69 61 6e 74 73 20 77 72 69 74 65 73 20 69  ariants writes i
1ee30 6e 74 6f 20 2a 70 70 53 74 6d 74 20 61 20 70 6f  nto *ppStmt a po
1ee40 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a  inter to a new.*
1ee50 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
1ee60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1ee70 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  or a pointer to 
1ee80 4e 55 4c 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e  NULL if zSql con
1ee90 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  tains.**        
1eea0 20 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20    nothing other 
1eeb0 74 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 20  than whitespace 
1eec0 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a  or comments..**.
1eed0 2a 2a 20 7b 48 31 33 30 31 39 7d 20 54 68 65 20  ** {H13019} The 
1eee0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1eef0 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
1ef00 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
1ef10 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  s return.**     
1ef20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
1ef30 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61   or an appropria
1ef40 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
1ef50 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  upon failure..**
1ef60 0a 2a 2a 20 7b 48 31 33 30 32 31 7d 20 42 65 66  .** {H13021} Bef
1ef70 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ore [sqlite3_pre
1ef80 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  pare(db,zSql,nBy
1ef90 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c  te,ppStmt,pzTail
1efa0 29 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20  )] or its.**    
1efb0 20 20 20 20 20 20 76 61 72 69 61 6e 74 73 20 72        variants r
1efc0 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 20  eturns an error 
1efd0 28 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72  (any value other
1efe0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
1eff0 5d 29 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ]),.**          
1f000 74 68 65 79 20 66 69 72 73 74 20 73 65 74 20 2a  they first set *
1f010 70 70 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a  ppStmt to NULL..
1f020 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
1f030 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
1f040 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1f050 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1f060 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1f070 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1f080 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1f090 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1f0a0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1f0b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1f0c0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1f0d0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1f0e0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1f0f0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1f100 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1f110 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1f120 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1f130 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1f140 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1f150 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1f160 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1f170 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
1f180 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1f190 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1f1a0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1f1b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1f1c0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1f1d0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
1f1e0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1f1f0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1f200 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1f210 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1f220 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1f230 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1f240 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1f250 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1f260 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1f270 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1f280 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1f290 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1f2a0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1f2b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f2c0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
1f2d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1f2e0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1f2f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1f300 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1f310 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1f320 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1f330 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1f340 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1f350 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1f360 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1f370 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1f380 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1f390 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1f3a0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1f3b0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1f3c0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1f3d0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1f3e0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1f3f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1f400 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
1f410 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1f420 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1f430 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1f440 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1f450 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1f460 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1f470 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1f480 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1f490 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1f4a0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1f4b0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1f4c0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1f4d0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1f4e0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1f4f0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1f500 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1f510 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1f520 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1f530 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
1f540 2a 20 43 41 50 49 52 45 46 3a 20 52 65 74 72 69  * CAPIREF: Retri
1f550 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
1f560 53 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48 31  SQL {H13100} <H1
1f570 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  3000>.**.** This
1f580 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
1f590 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
1f5a0 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
1f5b0 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
1f5c0 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
1f5d0 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
1f5e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f5f0 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
1f600 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
1f610 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
1f620 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f630 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
1f640 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1f650 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
1f660 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
1f670 33 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70 72  3101} If the [pr
1f680 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f690 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  ] passed as the 
1f6a0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20  argument to.**  
1f6b0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1f6c0 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70  _sql()] was comp
1f6d0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
1f6e0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1f6f0 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20  re_v2()] or.**  
1f700 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1f710 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1f720 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  , then [sqlite3_
1f730 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a 2a  sql()] returns.*
1f740 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69  *          a poi
1f750 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
1f760 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1f770 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55 54   containing a UT
1f780 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a  F-8 rendering.**
1f790 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
1f7a0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 74   original SQL st
1f7b0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b  atement..**.** {
1f7c0 48 31 33 31 30 32 7d 20 49 66 20 74 68 65 20 5b  H13102} If the [
1f7d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f7e0 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 68  nt] passed as th
1f7f0 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
1f800 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1f810 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f  e3_sql()] was co
1f820 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
1f830 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
1f840 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  pare()] or.**   
1f850 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1f860 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
1f870 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28  en [sqlite3_sql(
1f880 29 5d 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  )] returns a NUL
1f890 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1f8a0 20 7b 48 31 33 31 30 33 7d 20 54 68 65 20 73 74   {H13103} The st
1f8b0 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79  ring returned by
1f8c0 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53 29   [sqlite3_sql(S)
1f8d0 5d 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  ] is valid until
1f8e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1f8f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f900 6d 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65 74  ment] S is delet
1f910 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1f920 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a  3_finalize(S)]..
1f930 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1f940 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
1f950 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
1f960 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f970 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
1f980 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
1f990 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32 30   {H15000} <S2020
1f9a0 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
1f9b0 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
1f9c0 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
1f9d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1f9e0 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
1f9f0 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
1fa00 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1fa10 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
1fa20 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
1fa30 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
1fa40 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
1fa50 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
1fa60 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
1fa70 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
1fa80 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c 75   it stores. Valu
1fa90 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
1faa0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1fab0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
1fac0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
1fad0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
1fae0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
1faf0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
1fb00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1fb10 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
1fb20 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
1fb30 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
1fb40 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
1fb50 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
1fb60 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1fb70 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
1fb80 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
1fb90 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
1fba0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
1fbb0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
1fbc0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
1fbd0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
1fbe0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
1fbf0 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
1fc00 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
1fc10 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1fc20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
1fc30 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1fc40 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
1fc50 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
1fc60 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
1fc70 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
1fc80 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
1fc90 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
1fca0 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74    A internal mut
1fcb0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
1fcc0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
1fcd0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1fce0 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
1fcf0 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
1fd00 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
1fd10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1fd20 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
1fd30 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
1fd40 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
1fd50 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
1fd60 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
1fd70 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
1fd80 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
1fd90 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
1fda0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
1fdb0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
1fdc0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
1fdd0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
1fde0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
1fdf0 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
1fe00 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
1fe10 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
1fe20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
1fe30 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
1fe40 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
1fe50 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1fe60 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
1fe70 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
1fe80 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
1fe90 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
1fea0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
1feb0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
1fec0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
1fed0 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
1fee0 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
1fef0 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
1ff00 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70  etween between p
1ff10 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
1ff20 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
1ff30 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1ff40 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
1ff50 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
1ff60 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1ff70 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1ff80 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
1ff90 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
1ffa0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
1ffb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
1ffc0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1ffd0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1ffe0 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
1fff0 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
20000 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
20010 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
20020 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
20030 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
20040 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
20050 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
20060 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
20070 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
20080 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
20090 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
200a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
200b0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
200c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
200d0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
200e0 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
200f0 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
20100 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
20110 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
20120 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
20130 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
20140 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
20150 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20160 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
20170 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b  Context Object {
20180 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30 3e  H16001} <S20200>
20190 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
201a0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
201b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
201c0 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
201d0 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
201e0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
201f0 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
20200 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
20210 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
20220 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
20230 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
20240 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
20250 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
20260 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
20270 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
20280 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
20290 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
202a0 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
202b0 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
202c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
202d0 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
202e0 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
202f0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
20300 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
20310 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
20320 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
20330 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
20340 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
20350 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
20360 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
20370 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
20380 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
20390 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
203a0 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
203b0 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
203c0 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
203d0 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
203e0 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 48  ed Statements {H
203f0 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13500} <S70300>.
20400 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
20410 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
20420 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
20430 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
20440 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
20450 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
20460 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
20470 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
20480 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e  inding}.**.** In
20490 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73   the SQL strings
204a0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
204b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
204c0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
204d0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
204e0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
204f0 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e  y a parameter in
20500 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66 6f   one of these fo
20510 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  rms:.**.** <ul>.
20520 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
20530 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
20540 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
20550 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
20560 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
20570 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74  * In the paramet
20580 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61  er forms shown a
20590 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69  bove NNN is an i
205a0 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
205b0 2a 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61 6e  ** and VVV is an
205c0 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70   alpha-numeric p
205d0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54  arameter name. T
205e0 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
205f0 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
20600 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
20610 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
20620 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
20630 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
20640 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
20650 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
20660 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
20670 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
20680 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
20690 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
206a0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
206b0 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
206c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
206d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
206e0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
206f0 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
20700 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
20710 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
20720 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
20730 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
20740 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
20750 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
20760 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c  be set..** The l
20770 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
20780 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
20790 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74  ex of 1.  When t
207a0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
207b0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
207c0 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
207d0 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
207e0 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
207f0 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
20800 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
20810 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
20820 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20  urrence..** The 
20830 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
20840 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
20850 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
20860 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
20870 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
20880 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
20890 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69   desired.  The i
208a0 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
208b0 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
208c0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
208d0 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61  N..** The NNN va
208e0 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
208f0 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
20900 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
20910 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
20920 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
20930 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
20940 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
20950 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
20960 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
20970 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
20980 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
20990 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  ..**.** In those
209a0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
209b0 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
209c0 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
209d0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
209e0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
209f0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
20a00 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
20a10 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
20a20 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
20a30 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
20a40 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
20a50 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
20a60 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72  ..** If the four
20a70 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
20a80 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65  negative, the le
20a90 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
20aa0 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
20ab0 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
20ac0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
20ad0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
20ae0 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72  .** The fifth ar
20af0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
20b00 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
20b10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
20b20 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
20b30 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
20b40 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
20b50 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
20b60 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
20b70 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
20b80 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
20b90 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66 20  hed with it. If 
20ba0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
20bb0 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
20bc0 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
20bd0 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
20be0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
20bf0 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
20c00 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
20c10 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
20c20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
20c30 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
20c40 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  eed..** If the f
20c50 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
20c60 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
20c70 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
20c80 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
20c90 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
20ca0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
20cb0 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
20cc0 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
20cd0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
20ce0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
20cf0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
20d00 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
20d10 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
20d20 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
20d30 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
20d40 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
20d50 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62  oes.  A zeroblob
20d60 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
20d70 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
20d80 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
20d90 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
20da0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
20db0 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
20dc0 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
20dd0 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
20de0 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
20df0 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
20e00 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
20e10 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
20e20 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
20e30 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
20e40 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
20e50 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
20e60 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c  * A negative val
20e70 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
20e80 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
20e90 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
20ea0 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  B..**.** The sql
20eb0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
20ec0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
20ed0 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b  alled after.** [
20ee0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20ef0 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76  v2()] (and its v
20f00 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c  ariants) or [sql
20f10 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e  ite3_reset()] an
20f20 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c  d.** before [sql
20f30 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
20f40 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f   Bindings are no
20f50 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
20f60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
20f70 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55  )] routine..** U
20f80 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
20f90 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
20fa0 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
20fb0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
20fc0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
20fd0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
20fe0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
20ff0 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f  f.** anything go
21000 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49  es wrong.  [SQLI
21010 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
21020 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
21030 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
21040 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
21050 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
21060 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
21070 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
21080 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
21090 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  E] might be retu
210a0 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f  rned if these ro
210b0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
210c0 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61  d on a.** virtua
210d0 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69  l machine that i
210e0 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74  s the wrong stat
210f0 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61  e or which has a
21100 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61  lready been fina
21110 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74  lized..** Detect
21120 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73  ion of misuse is
21130 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70   unreliable.  Ap
21140 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
21150 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20  d not depend.** 
21160 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  on SQLITE_MISUSE
21170 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54   returns.  SQLIT
21180 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65  E_MISUSE is inte
21190 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  nded to indicate
211a0 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72   a.** a logic er
211b0 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69  ror in the appli
211c0 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20  cation.  Future 
211d0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
211e0 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69  te might.** pani
211f0 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 65  c rather than re
21200 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
21210 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  SE..**.** See al
21220 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
21230 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
21240 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
21250 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
21260 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
21270 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21280 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
21290 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
212a0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 36 7d  :.**.** {H13506}
212b0 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d   The [SQL statem
212c0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65  ent compiler] re
212d0 63 6f 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 20  cognizes tokens 
212e0 6f 66 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a 20  of the forms.** 
212f0 20 20 20 20 20 20 20 20 20 22 3f 22 2c 20 22 3f           "?", "?
21300 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20 22 3a  NNN", "$VVV", ":
21310 56 56 56 22 2c 20 61 6e 64 20 22 40 56 56 56 22  VVV", and "@VVV"
21320 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65   as SQL paramete
21330 72 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rs,.**          
21340 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79  where NNN is any
21350 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65   sequence of one
21360 20 6f 72 20 6d 6f 72 65 20 64 69 67 69 74 73 0a   or more digits.
21370 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
21380 77 68 65 72 65 20 56 56 56 20 69 73 20 61 6e 79  where VVV is any
21390 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65   sequence of one
213a0 20 6f 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e 75   or more alphanu
213b0 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20  meric.**        
213c0 20 20 63 68 61 72 61 63 74 65 72 73 20 6f 72 20    characters or 
213d0 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  "::" optionally 
213e0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 73 74  followed by a st
213f0 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 0a  ring containing.
21400 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 73  **          no s
21410 70 61 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 69  paces and contai
21420 6e 65 64 20 77 69 74 68 69 6e 20 70 61 72 65 6e  ned within paren
21430 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  theses..**.** {H
21440 31 33 35 30 39 7d 20 54 68 65 20 69 6e 69 74 69  13509} The initi
21450 61 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53  al value of an S
21460 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
21470 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  NULL..**.** {H13
21480 35 31 32 7d 20 54 68 65 20 69 6e 64 65 78 20 6f  512} The index o
21490 66 20 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 72  f an "?" SQL par
214a0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6c 61  ameter is one la
214b0 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a  rger than the.**
214c0 20 20 20 20 20 20 20 20 20 20 6c 61 72 67 65 73            larges
214d0 74 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70  t index of SQL p
214e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
214f0 6c 65 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a  left, or 1 if.**
21500 20 20 20 20 20 20 20 20 20 20 74 68 65 20 22 3f            the "?
21510 22 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73  " is the leftmos
21520 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 2e  t SQL parameter.
21530 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 35 7d 20  .**.** {H13515} 
21540 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  The index of an 
21550 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d  "?NNN" SQL param
21560 65 74 65 72 20 69 73 20 74 68 65 20 69 6e 74 65  eter is the inte
21570 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  ger NNN..**.** {
21580 48 31 33 35 31 38 7d 20 54 68 65 20 69 6e 64 65  H13518} The inde
21590 78 20 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c 20  x of an ":VVV", 
215a0 22 24 56 56 56 22 2c 20 6f 72 20 22 40 56 56 56  "$VVV", or "@VVV
215b0 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  " SQL parameter 
215c0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  is.**          t
215d0 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 69  he same as the i
215e0 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74  ndex of leftmost
215f0 20 6f 63 63 75 72 72 65 6e 63 65 73 20 6f 66 20   occurrences of 
21600 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
21610 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c 20       parameter, 
21620 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e  or one more than
21630 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64   the largest ind
21640 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20  ex over all.**  
21650 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
21660 72 73 20 74 6f 20 74 68 65 20 6c 65 66 74 20 69  rs to the left i
21670 66 20 74 68 69 73 20 69 73 20 74 68 65 20 66 69  f this is the fi
21680 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a  rst occurrence.*
21690 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
216a0 69 73 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72  is parameter, or
216b0 20 31 20 69 66 20 74 68 69 73 20 69 73 20 74 68   1 if this is th
216c0 65 20 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 6d  e leftmost param
216d0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  eter..**.** {H13
216e0 35 32 31 7d 20 54 68 65 20 5b 53 51 4c 20 73 74  521} The [SQL st
216f0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
21700 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  ] fails with an 
21710 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a 2a  [SQLITE_RANGE].*
21720 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72  *          error
21730 20 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f 66   if the index of
21740 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
21750 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31  r is less than 1
21760 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
21770 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
21780 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53 51   compile-time SQ
21790 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c  LITE_MAX_VARIABL
217a0 45 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20 20  E_NUMBER.**     
217b0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a       parameter..
217c0 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 34 7d 20 43  **.** {H13524} C
217d0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
217e0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c  _bind_text | sql
217f0 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c  ite3_bind(S,N,V,
21800 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
21810 20 20 61 73 73 6f 63 69 61 74 65 20 74 68 65 20    associate the 
21820 76 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c 6c  value V with all
21830 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
21840 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20  having an.**    
21850 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20 4e        index of N
21860 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
21870 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
21880 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 37 7d 20 43  **.** {H13527} C
21890 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
218a0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c  _bind_text | sql
218b0 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e  ite3_bind(S,N,..
218c0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
218d0 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 63  override prior c
218e0 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73 61  alls with the sa
218f0 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20 61  me values of S a
21900 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  nd N..**.** {H13
21910 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 73  530} Bindings es
21920 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73 71  tablished by [sq
21930 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
21940 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53  | sqlite3_bind(S
21950 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
21960 20 20 20 70 65 72 73 69 73 74 20 61 63 72 6f 73     persist acros
21970 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  s calls to [sqli
21980 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a  te3_reset(S)]..*
21990 2a 0a 2a 2a 20 7b 48 31 33 35 33 33 7d 20 49 6e  *.** {H13533} In
219a0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
219b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e  e3_bind_blob(S,N
219c0 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,L,D)],.**    
219d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
219e0 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
219f0 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
21a00 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
21a10 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
21a20 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e  L,D)] SQLite bin
21a30 64 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a  ds the first L.*
21a40 2a 20 20 20 20 20 20 20 20 20 20 62 79 74 65 73  *          bytes
21a50 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
21a60 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
21a70 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a  o by V, when L.*
21a80 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f  *          is no
21a90 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
21aa0 2a 20 7b 48 31 33 35 33 36 7d 20 49 6e 20 63 61  * {H13536} In ca
21ab0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
21ac0 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
21ad0 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  L,D)] or.**     
21ae0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
21af0 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
21b00 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e  L,D)] SQLite bin
21b10 64 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a 2a  ds characters.**
21b20 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 56            from V
21b30 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
21b40 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
21b50 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61  r when L is nega
21b60 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  tive..**.** {H13
21b70 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  539} In calls to
21b80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
21b90 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  lob(S,N,V,L,D)],
21ba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
21bb0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
21bc0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a  S,N,V,L,D)], or.
21bd0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
21be0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
21bf0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65  (S,N,V,L,D)] whe
21c00 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63 69  n D is the speci
21c10 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  al.**          c
21c20 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f  onstant [SQLITE_
21c30 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20  STATIC], SQLite 
21c40 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
21c50 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20   value V.**     
21c60 20 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e 20       is held in 
21c70 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 64  static unmanaged
21c80 20 73 70 61 63 65 20 74 68 61 74 20 77 69 6c 6c   space that will
21c90 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20   not change.**  
21ca0 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 74          during t
21cb0 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74  he lifetime of t
21cc0 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a  he binding..**.*
21cd0 2a 20 7b 48 31 33 35 34 32 7d 20 49 6e 20 63 61  * {H13542} In ca
21ce0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
21cf0 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
21d00 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
21d10 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
21d20 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
21d30 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
21d40 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
21d50 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
21d60 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65  )] when D is the
21d70 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20   special.**     
21d80 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53       constant [S
21d90 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
21da0 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d 61  , the routine ma
21db0 6b 65 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  kes a.**        
21dc0 20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f    private copy o
21dd0 66 20 74 68 65 20 76 61 6c 75 65 20 56 20 62 65  f the value V be
21de0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
21df0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 35 7d 20  .**.** {H13545} 
21e00 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
21e10 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53  ite3_bind_blob(S
21e20 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20  ,N,V,L,D)],.**  
21e30 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
21e40 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
21e50 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,L,D)], or.**   
21e60 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
21e70 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c  bind_text16(S,N,
21e80 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69  V,L,D)] when D i
21e90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
21ea0 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 75 6e  *          a fun
21eb0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e  ction, SQLite in
21ec0 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63 74  vokes that funct
21ed0 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 74  ion to destroy t
21ee0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  he.**          v
21ef0 61 6c 75 65 20 56 20 61 66 74 65 72 20 69 74 20  alue V after it 
21f00 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
21f10 6e 67 20 74 68 65 20 76 61 6c 75 65 20 56 2e 0a  ng the value V..
21f20 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 38 7d 20 49  **.** {H13548} I
21f30 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
21f40 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
21f50 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20  b(S,N,V,L)] the 
21f60 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20  value bound.**  
21f70 20 20 20 20 20 20 20 20 69 73 20 61 20 42 4c 4f          is a BLO
21f80 42 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f 72  B of L bytes, or
21f90 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
21fa0 4c 4f 42 20 69 66 20 4c 20 69 73 20 6e 65 67 61  LOB if L is nega
21fb0 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  tive..**.** {H13
21fc0 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  551} In calls to
21fd0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
21fe0 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65  alue(S,N,V)] the
21ff0 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a   V argument may.
22000 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 20 65  **          be e
22010 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74  ither a [protect
22020 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
22030 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a  ] object or an.*
22040 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70 72  *          [unpr
22050 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
22060 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  value] object..*
22070 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
22080 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
22090 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
220a0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
220b0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
220c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
220d0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
220e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
220f0 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
22100 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
22110 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
22120 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
22130 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
22140 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
22150 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
22160 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
22170 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
22180 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
22190 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
221a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
221b0 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
221c0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
221d0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
221e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
221f0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
22200 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
22210 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
22220 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
22230 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
22240 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
22250 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
22260 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
22270 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
22280 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
22290 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
222a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
222b0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
222c0 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33 36  Parameters {H136
222d0 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  00} <S70300>.**.
222e0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
222f0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
22300 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
22310 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
22320 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
22330 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
22340 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
22350 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
22360 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
22370 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
22380 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
22390 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
223a0 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
223b0 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
223c0 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
223d0 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
223e0 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
223f0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
22400 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  time..**.** This
22410 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
22420 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
22430 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
22440 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
22450 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
22460 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
22470 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
22480 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
22490 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
224a0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
224b0 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
224c0 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61  rs of the ?NNN a
224d0 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
224e0 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
224f0 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a   the list..**.**
22500 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
22510 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
22520 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
22530 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
22540 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
22550 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
22560 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
22570 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
22580 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
22590 0a 2a 2a 20 7b 48 31 33 36 30 31 7d 20 54 68 65  .** {H13601} The
225a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
225b0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53  arameter_count(S
225c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
225d0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
225e0 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64   the largest ind
225f0 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61  ex of all SQL pa
22600 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68 65 0a  rameters in the.
22610 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
22620 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22630 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20 63 6f   S, or 0 if S co
22640 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61  ntains no SQL pa
22650 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74  rameters..*/.int
22660 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
22670 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
22680 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
22690 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
226a0 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
226b0 72 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30 7d  rameter {H13620}
226c0 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70300>.**.** 
226d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
226e0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
226f0 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  o the name of th
22700 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70  e n-th.** [SQL p
22710 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b  arameter] in a [
22720 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22730 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61  nt]..** SQL para
22740 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
22750 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
22760 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
22770 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
22780 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
22790 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
227a0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
227b0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
227c0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
227d0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
227e0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
227f0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
22800 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
22810 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
22820 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20  of the name..** 
22830 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
22840 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
22850 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
22860 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
22870 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61  ame.** and are a
22880 6c 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20  lso referred to 
22890 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  as "anonymous pa
228a0 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
228b0 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20   The first host 
228c0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
228d0 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
228e0 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65   0..**.** If the
228f0 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20   value n is out 
22900 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
22910 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65  he n-th paramete
22920 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
22930 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
22940 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65  eturned.  The re
22950 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
22960 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
22970 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
22980 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
22990 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
229a0 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
229b0 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
229c0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
229d0 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
229e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
229f0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
22a00 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
22a10 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
22a20 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
22a30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
22a40 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
22a50 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
22a60 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
22a70 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
22a80 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
22a90 2a 20 7b 48 31 33 36 32 31 7d 20 54 68 65 20 5b  * {H13621} The [
22aa0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
22ab0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29  ameter_name(S,N)
22ac0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
22ad0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
22ae0 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
22af0 67 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f 66  g of the name of
22b00 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
22b10 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20  er in.**        
22b20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20    the [prepared 
22b30 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76  statement] S hav
22b40 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a  ing index N, or.
22b50 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c  **          NULL
22b60 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   if there is no 
22b70 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69  SQL parameter wi
22b80 74 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66  th index N or if
22b90 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
22ba0 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20   parameter with 
22bb0 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e  index N is an an
22bc0 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
22bd0 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  r "?"..*/.const 
22be0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
22bf0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
22c00 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
22c10 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
22c20 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
22c30 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
22c40 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b  h A Given Name {
22c50 48 31 33 36 34 30 7d 20 3c 53 37 30 33 30 30 3e  H13640} <S70300>
22c60 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
22c70 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
22c80 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
22c90 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 65  n its name.  The
22ca0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
22cb0 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
22cc0 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
22cd0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
22ce0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
22cf0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
22d00 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
22d10 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
22d20 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
22d30 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
22d40 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 61  s found.  The pa
22d50 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
22d60 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
22d70 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
22d80 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
22d90 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
22da0 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
22db0 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
22dc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
22dd0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
22de0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
22df0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
22e00 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
22e10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
22e20 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
22e30 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
22e40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
22e50 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ndex()]..**.** I
22e60 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
22e70 20 7b 48 31 33 36 34 31 7d 20 54 68 65 20 5b 73   {H13641} The [s
22e80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
22e90 6d 65 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e 29  meter_index(S,N)
22ea0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
22eb0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
22ec0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 53 51 4c  the index of SQL
22ed0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
22ee0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
22ef0 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20  ement].**       
22f00 20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20     S whose name 
22f10 6d 61 74 63 68 65 73 20 74 68 65 20 55 54 46 2d  matches the UTF-
22f20 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30  8 string N, or 0
22f30 20 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20   if there is.** 
22f40 20 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63           no matc
22f50 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  h..*/.int sqlite
22f60 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
22f70 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
22f80 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
22f90 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
22fa0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
22fb0 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
22fc0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
22fd0 65 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c  ement {H13660} <
22fe0 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f  S70300>.**.** Co
22ff0 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
23000 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
23010 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23020 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
23030 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
23040 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
23050 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
23060 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23070 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72  ]..** Use this r
23080 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
23090 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
230a0 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ers to NULL..**.
230b0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
230c0 2a 0a 2a 2a 20 7b 48 31 33 36 36 31 7d 20 54 68  *.** {H13661} Th
230d0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
230e0 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e  _bindings(S)] in
230f0 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 61  terface resets a
23100 6c 6c 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20  ll SQL.**       
23110 20 20 20 70 61 72 61 6d 65 74 65 72 20 62 69 6e     parameter bin
23120 64 69 6e 67 73 20 69 6e 20 74 68 65 20 5b 70 72  dings in the [pr
23130 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23140 5d 20 53 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c  ] S back to NULL
23150 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23160 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
23170 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
23180 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23190 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
231a0 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
231b0 65 74 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 30  et {H13710} <S10
231c0 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  700>.**.** Retur
231d0 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
231e0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
231f0 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
23200 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
23210 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23220 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ]. This routine 
23230 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
23240 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
23250 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
23260 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
23270 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
23280 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
23290 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
232a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 31 31 7d 20  .**.** {H13711} 
232b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
232c0 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e  umn_count(S)] in
232d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
232e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
232f0 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e            column
23300 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
23310 73 65 74 20 67 65 6e 65 72 61 74 65 64 20 62 79  set generated by
23320 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
23330 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20  tatement] S,.** 
23340 20 20 20 20 20 20 20 20 20 6f 72 20 30 20 69 66           or 0 if
23350 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65   S does not gene
23360 72 61 74 65 20 61 20 72 65 73 75 6c 74 20 73 65  rate a result se
23370 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
23380 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
23390 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
233a0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
233b0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
233c0 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
233d0 65 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 31 30  et {H13720} <S10
233e0 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  700>.**.** These
233f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
23400 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
23410 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
23420 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
23430 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
23440 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
23450 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c  tement.  The sql
23460 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
23470 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
23480 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
23490 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
234a0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
234b0 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
234c0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
234d0 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
234e0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
234f0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
23500 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65  -16 string.  The
23510 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
23520 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
23530 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
23540 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
23550 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
23560 74 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63 6f  tement. The seco
23570 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
23580 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
23590 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 6d  mber.  The leftm
235a0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
235b0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68  mber 0..**.** Th
235c0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
235d0 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
235e0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
235f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
23600 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
23610 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
23620 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
23630 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
23640 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
23650 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
23660 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
23670 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
23680 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
23690 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69  n..**.** If sqli
236a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
236b0 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
236c0 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
236d0 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
236e0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
236f0 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
23700 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
23710 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
23720 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
23730 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
23740 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
23750 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
23760 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
23770 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
23780 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
23790 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
237a0 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
237b0 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
237c0 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
237d0 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
237e0 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
237f0 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
23800 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
23810 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
23820 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a   the next..**.**
23830 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
23840 2a 2a 20 7b 48 31 33 37 32 31 7d 20 41 20 73 75  ** {H13721} A su
23850 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
23860 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
23870 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
23880 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,N)].**        
23890 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75    interface retu
238a0 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  rns the name of 
238b0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28  the Nth column (
238c0 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20  where 0 is.**   
238d0 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d         the leftm
238e0 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20  ost column) for 
238f0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
23900 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
23910 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
23920 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65  ement] S as a ze
23930 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
23940 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
23950 2a 20 7b 48 31 33 37 32 33 7d 20 41 20 73 75 63  * {H13723} A suc
23960 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
23970 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
23980 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
23990 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  (S,N)].**       
239a0 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74     interface ret
239b0 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  urns the name of
239c0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
239d0 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20  (where 0 is.**  
239e0 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 74          the left
239f0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72  most column) for
23a00 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
23a10 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
23a20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
23a30 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a  tement] S as a z
23a40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
23a50 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  TF-16 string.** 
23a60 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 20           in the 
23a70 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
23a80 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 34  r..**.** {H13724
23a90 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
23aa0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e  olumn_name()] an
23ab0 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
23ac0 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20  n_name16()].**  
23ad0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
23ae0 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c  es return a NULL
23af0 20 70 6f 69 6e 74 65 72 20 69 66 20 74 68 65 79   pointer if they
23b00 20 61 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a   are unable to.*
23b10 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63  *          alloc
23b20 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
23b30 6c 64 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20  ld their normal 
23b40 72 65 74 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a  return strings..
23b50 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 35 7d 20 49  **.** {H13725} I
23b60 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  f the N paramete
23b70 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  r to [sqlite3_co
23b80 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  lumn_name(S,N)] 
23b90 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
23ba0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
23bb0 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f  ame16(S,N)] is o
23bc0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
23bd0 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
23be0 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74    interfaces ret
23bf0 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  urn a NULL point
23c00 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32  er..**.** {H1372
23c10 36 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  6} The strings r
23c20 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
23c30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
23c40 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  S,N)] and.**    
23c50 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
23c60 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e  olumn_name16(S,N
23c70 29 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  )] are valid unt
23c80 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20  il the next.**  
23c90 20 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20          call to 
23ca0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77  either routine w
23cb0 69 74 68 20 74 68 65 20 73 61 6d 65 20 53 20 61  ith the same S a
23cc0 6e 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a  nd N parameters.
23cd0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75  **          or u
23ce0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69  ntil [sqlite3_fi
23cf0 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61  nalize(S)] is ca
23d00 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  lled..**.** {H13
23d10 37 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75  727} When a resu
23d20 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b  lt column of a [
23d30 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
23d40 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20  t contains.**   
23d50 20 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61         an AS cla
23d60 75 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66  use, the name of
23d70 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
23d80 74 68 65 20 69 64 65 6e 74 69 66 69 65 72 0a 2a  the identifier.*
23d90 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68  *          to th
23da0 65 20 72 69 67 68 74 20 6f 66 20 74 68 65 20 41  e right of the A
23db0 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f  S keyword..*/.co
23dc0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
23dd0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
23de0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23df0 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
23e00 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23e10 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
23e20 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
23e30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
23e40 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
23e50 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20   A Query Result 
23e60 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30  {H13740} <S10700
23e70 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
23e80 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
23e90 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
23ea0 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20  ine what column 
23eb0 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65  of what.** table
23ec0 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61   in which databa
23ed0 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  se a result of a
23ee0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
23ef0 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a  ent comes from..
23f00 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** The name of t
23f10 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
23f20 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
23f30 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
23f40 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
23f50 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
23f60 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61  ring.  The _data
23f70 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
23f80 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
23f90 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
23fa0 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
23fb0 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
23fc0 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
23fd0 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
23fe0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
23ff0 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54  olumn name..** T
24000 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
24010 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
24020 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
24030 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
24040 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
24050 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
24060 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
24070 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
24080 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
24090 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
240a0 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
240b0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  g..**.** The nam
240c0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
240d0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
240e0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
240f0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
24100 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
24110 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  umn..**.** The f
24120 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
24130 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
24140 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61  alls is a [prepa
24150 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
24160 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
24170 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
24180 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
24190 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
241a0 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
241b0 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
241c0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
241d0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
241e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e  ..**.** If the N
241f0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
24200 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
24210 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
24220 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
24230 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
24240 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
24250 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
24260 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
24270 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73  n.** NULL.  Thes
24280 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
24290 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
242a0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
242b0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
242c0 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77   occurs.  Otherw
242d0 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
242e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
242f0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
24300 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64  se, table.** and
24310 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
24320 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
24330 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
24340 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69  rom..**.** As wi
24350 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
24360 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
24370 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22  postfixed with "
24380 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
24390 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
243a0 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20  ings, the other 
243b0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
243c0 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a   UTF-8. {END}.**
243d0 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61  .** These APIs a
243e0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
243f0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
24400 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
24410 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
24420 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
24430 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
24440 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20  rocessor symbol 
24450 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  defined..**.** {
24460 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77  A13751}.** If tw
24470 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
24480 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
24490 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
244a0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
244b0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
244c0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
244d0 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
244e0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
244f0 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
24500 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
24510 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
24520 2a 2a 20 7b 48 31 33 37 34 31 7d 20 54 68 65 20  ** {H13741} The 
24530 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24540 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c  database_name(S,
24550 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
24560 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
24570 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
24580 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
24590 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ed name of the d
245a0 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69  atabase from whi
245b0 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ch the.**       
245c0 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f     Nth result co
245d0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65  lumn of the [pre
245e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
245f0 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c   S is extracted,
24600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
24610 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20  NULL if the Nth 
24620 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
24630 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73   general express
24640 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
24650 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
24660 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
24670 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d  to store the nam
24680 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 32  e..**.** {H13742
24690 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
246a0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
246b0 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65  ame16(S,N)] inte
246c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
246d0 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
246e0 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69   the UTF-16 nati
246f0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65  ve byte order ze
24700 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
24710 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
24720 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  se.**          f
24730 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74  rom which the Nt
24740 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
24750 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  of the [prepared
24760 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
24770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 74  .**          ext
24780 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
24790 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
247a0 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65  n of S is a gene
247b0 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  ral expression.*
247c0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
247d0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
247e0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74  ate memory to st
247f0 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
24800 0a 2a 2a 20 7b 48 31 33 37 34 33 7d 20 54 68 65  .** {H13743} The
24810 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24820 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29  _table_name(S,N)
24830 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
24840 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
24850 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38         the UTF-8
24860 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
24870 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62   name of the tab
24880 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  le from which th
24890 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
248a0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
248b0 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  of the [prepared
248c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
248d0 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20   extracted,.**  
248e0 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20          or NULL 
248f0 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
24900 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65  n of S is a gene
24910 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  ral expression.*
24920 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
24930 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
24940 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74  ate memory to st
24950 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
24960 0a 2a 2a 20 7b 48 31 33 37 34 34 7d 20 54 68 65  .** {H13744} The
24970 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24980 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c  _table_name16(S,
24990 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
249a0 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
249b0 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
249c0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
249d0 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69  order zero-termi
249e0 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
249f0 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20  e table.**      
24a00 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20 74      from which t
24a10 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
24a20 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65  lumn of the [pre
24a30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24a40 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20   S is.**        
24a50 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20    extracted, or 
24a60 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20  NULL if the Nth 
24a70 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
24a80 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73   general express
24a90 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
24aa0 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
24ab0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
24ac0 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d  to store the nam
24ad0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 35  e..**.** {H13745
24ae0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
24af0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
24b00 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
24b10 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
24b20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
24b30 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
24b40 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
24b50 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
24b60 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a  from which the.*
24b70 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
24b80 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
24b90 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24ba0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78  atement] S is ex
24bb0 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20  tracted,.**     
24bc0 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20       or NULL if 
24bd0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
24be0 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
24bf0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
24c00 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
24c10 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
24c20 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
24c30 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
24c40 20 7b 48 31 33 37 34 36 7d 20 54 68 65 20 5b 73   {H13746} The [s
24c50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
24c60 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  igin_name16(S,N)
24c70 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
24c80 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
24c90 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31         the UTF-1
24ca0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
24cb0 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  der zero-termina
24cc0 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
24cd0 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20  table.**        
24ce0 20 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68    column from wh
24cf0 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73 75  ich the Nth resu
24d00 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  lt column of the
24d10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
24d20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24d30 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64  ] S is extracted
24d40 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
24d50 20 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20   Nth column.**  
24d60 20 20 20 20 20 20 20 20 6f 66 20 53 20 69 73 20          of S is 
24d70 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
24d80 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c  sion or if unabl
24d90 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
24da0 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  mory.**         
24db0 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
24dc0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
24dd0 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  8} The return va
24de0 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20  lues from.**    
24df0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
24e00 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
24e10 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
24e20 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
24e30 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  ].**          ar
24e40 65 20 76 61 6c 69 64 20 66 6f 72 20 74 68 65 20  e valid for the 
24e50 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20  lifetime of the 
24e60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24e70 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ent].**         
24e80 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e   or until the en
24e90 63 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65  coding is change
24ea0 64 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74  d by another met
24eb0 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20  adata.**        
24ec0 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c    interface call
24ed0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72   for the same pr
24ee0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24ef0 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
24f00 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
24f10 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 20 49  **.** {A13751} I
24f20 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
24f30 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
24f40 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20  r more.**       
24f50 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
24f60 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
24f70 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
24f80 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
24f90 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 74  *          for t
24fa0 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
24fb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
24fc0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
24fd0 2a 20 20 20 20 20 20 20 20 20 20 61 74 20 74 68  *          at th
24fe0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
24ff0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
25000 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63   undefined..*/.c
25010 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
25020 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
25030 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
25040 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
25050 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
25060 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
25070 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
25080 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
25090 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
250a0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
250b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
250c0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
250d0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
250e0 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
250f0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
25100 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
25110 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
25120 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
25130 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
25140 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
25150 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
25160 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
25170 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
25180 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
25190 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
251a0 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48   Query Result {H
251b0 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a  13760} <S10700>.
251c0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
251d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
251e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
251f0 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
25200 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
25210 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
25220 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
25230 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
25240 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
25250 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
25260 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
25270 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
25280 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
25290 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
252a0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
252b0 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
252c0 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
252d0 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20  ed.  If the Nth 
252e0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
252f0 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
25300 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
25310 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
25320 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
25330 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68   returned..** Th
25340 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
25350 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
25360 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d  8 encoded. {END}
25370 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
25380 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
25390 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
253a0 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
253b0 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
253c0 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
253d0 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
253e0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
253f0 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
25400 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
25410 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
25420 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
25430 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
25440 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
25450 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
25460 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
25470 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
25480 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
25490 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
254a0 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53   (i==0)..**.** S
254b0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
254c0 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
254d0 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63  ng.  So just bec
254e0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
254f0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
25500 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
25510 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
25520 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
25530 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
25540 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
25550 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
25560 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
25570 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
25580 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
25590 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
255a0 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70  not static.  Typ
255b0 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
255c0 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
255d0 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
255e0 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
255f0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
25600 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
25610 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
25620 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 31  S:.**.** {H13761
25630 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  }  A successful 
25640 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
25650 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
25660 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61  (S,N)] returns a
25670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 7a 65  .**           ze
25680 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
25690 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  F-8 string conta
256a0 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72  ining the declar
256b0 65 64 20 64 61 74 61 74 79 70 65 0a 2a 2a 20 20  ed datatype.**  
256c0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
256d0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
256e0 74 20 61 70 70 65 61 72 73 20 61 73 20 74 68 65  t appears as the
256f0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d   Nth column (num
25700 62 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  bered.**        
25710 20 20 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68     from 0) of th
25720 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20  e result set to 
25730 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25740 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
25750 2a 20 7b 48 31 33 37 36 32 7d 20 20 41 20 73 75  * {H13762}  A su
25760 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
25770 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
25780 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29  _decltype16(S,N)
25790 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  ].**           r
257a0 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65  eturns a zero-te
257b0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20  rminated UTF-16 
257c0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
257d0 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  r string.**     
257e0 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67        containing
257f0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64 61   the declared da
25800 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  tatype of the ta
25810 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
25820 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20  appears.**      
25830 20 20 20 20 20 61 73 20 74 68 65 20 4e 74 68 20       as the Nth 
25840 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64  column (numbered
25850 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20   from 0) of the 
25860 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68  result set to th
25870 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  e.**           [
25880 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25890 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  nt] S..**.** {H1
258a0 33 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c  3763}  If N is l
258b0 65 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20  ess than 0 or N 
258c0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
258d0 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20  or equal to.**  
258e0 20 20 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d           the num
258f0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
25900 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
25910 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a  statement] S,.**
25920 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66             or if
25930 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
25940 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70 72 65  of S is an expre
25950 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
25960 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 20 20  y rather.**     
25970 20 20 20 20 20 20 74 68 61 6e 20 61 20 74 61 62        than a tab
25980 6c 65 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66  le column, or if
25990 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
259a0 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20  tion failure.** 
259b0 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73            occurs
259c0 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67   during encoding
259d0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68   conversions, th
259e0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  en.**           
259f0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
25a00 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
25a10 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20  e(S,N)] or.**   
25a20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
25a30 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
25a40 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20  16(S,N)] return 
25a50 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  NULL..*/.const c
25a60 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
25a70 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
25a80 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
25a90 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
25aa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
25ab0 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
25ac0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
25ad0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
25ae0 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
25af0 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c  ement {H13200} <
25b00 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66  S10000>.**.** Af
25b10 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
25b20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
25b30 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
25b40 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
25b50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
25b60 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
25b70 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
25b80 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
25b90 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
25ba0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
25bb0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
25bc0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
25bd0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
25be0 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
25bf0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
25c00 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
25c10 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
25c20 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
25c30 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
25c40 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
25c50 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
25c60 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
25c70 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
25c80 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
25c90 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
25ca0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
25cb0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
25cc0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
25cd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
25ce0 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
25cf0 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
25d00 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
25d10 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
25d20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25d30 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
25d40 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
25d50 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
25d60 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
25d70 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
25d80 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
25d90 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
25da0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
25db0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
25dc0 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
25dd0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
25de0 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
25df0 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
25e00 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
25e10 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
25e20 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
25e30 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
25e40 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
25e50 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
25e60 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
25e70 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
25e80 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
25e90 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
25ea0 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
25eb0 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
25ec0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
25ed0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
25ee0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
25ef0 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
25f00 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
25f10 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
25f20 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
25f30 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65  its job.  If the
25f40 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
25f50 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
25f60 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
25f70 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
25f80 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
25f90 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
25fa0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
25fb0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
25fc0 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
25fd0 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
25fe0 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63  thin a.** explic
25ff0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
26000 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
26010 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
26020 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
26030 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
26040 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
26050 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
26060 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
26070 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
26080 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
26090 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
260a0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
260b0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
260c0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
260d0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
260e0 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
260f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
26100 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
26110 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
26120 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
26130 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
26140 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
26150 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
26160 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
26170 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
26180 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
26190 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
261a0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
261b0 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
261c0 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
261d0 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
261e0 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
261f0 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
26200 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
26210 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
26220 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
26230 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
26240 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
26250 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
26260 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  a..**.** [SQLITE
26270 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
26280 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
26290 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
262a0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
262b0 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
262c0 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
262d0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
262e0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
262f0 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
26300 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
26310 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
26320 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
26330 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57  _errmsg()]..** W
26340 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
26350 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
26360 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
26370 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
26380 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
26390 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
263a0 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
263b0 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
263c0 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
263d0 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
263e0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
263f0 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
26400 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
26410 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74  tatement].  In t
26420 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
26430 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
26440 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
26450 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
26460 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
26470 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
26480 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
26490 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
264a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
264b0 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
264c0 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
264d0 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
264e0 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
264f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
26500 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
26510 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
26520 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
26530 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
26540 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
26550 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
26560 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
26570 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
26580 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
26590 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
265a0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
265b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
265c0 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
265d0 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
265e0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
265f0 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
26600 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
26610 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
26620 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
26630 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
26640 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
26650 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
26660 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
26670 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
26680 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
26690 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
266a0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
266b0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
266c0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
266d0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
266e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
266f0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
26700 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
26710 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
26720 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
26730 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
26740 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
26750 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
26760 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
26770 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
26780 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
26790 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
267a0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
267b0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
267c0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
267d0 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
267e0 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
267f0 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
26800 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26810 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
26820 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
26830 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
26840 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
26850 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
26860 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
26870 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
26880 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
26890 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
268a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
268b0 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
268c0 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
268d0 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
268e0 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
268f0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
26900 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommended..**.** 
26910 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
26920 2a 20 7b 48 31 33 32 30 32 7d 20 20 49 66 20 74  * {H13202}  If t
26930 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
26940 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61  tement] S is rea
26950 64 79 20 74 6f 20 62 65 20 72 75 6e 2c 20 74 68  dy to be run, th
26960 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  en.**           
26970 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
26980 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61 74 20  ] advances that 
26990 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
269a0 6e 74 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20  nt until.**     
269b0 20 20 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f 6e        completion
269c0 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73 20   or until it is 
269d0 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 20  ready to return 
269e0 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74  another row of t
269f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  he.**           
26a00 72 65 73 75 6c 74 20 73 65 74 2c 20 6f 72 20 75  result set, or u
26a10 6e 74 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65 33  ntil an [sqlite3
26a20 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74  _interrupt | int
26a30 65 72 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20 20  errupt].**      
26a40 20 20 20 20 20 6f 72 20 61 20 72 75 6e 2d 74 69       or a run-ti
26a50 6d 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  me error occurs.
26a60 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 34 7d 20  .**.** {H15304} 
26a70 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20   When a call to 
26a80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
26a90 5d 20 63 61 75 73 65 73 20 74 68 65 20 5b 70 72  ] causes the [pr
26aa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26ab0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 53  ].**           S
26ac0 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c   to run to compl
26ad0 65 74 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63 74  etion, the funct
26ae0 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ion returns [SQL
26af0 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a  ITE_DONE]..**.**
26b00 20 7b 48 31 35 33 30 36 7d 20 20 57 68 65 6e 20   {H15306}  When 
26b10 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
26b20 65 33 5f 73 74 65 70 28 53 29 5d 20 73 74 6f 70  e3_step(S)] stop
26b30 73 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  s because it is 
26b40 72 65 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20 20  ready to.**     
26b50 20 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e 6f        return ano
26b60 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 20  ther row of the 
26b70 72 65 73 75 6c 74 20 73 65 74 2c 20 69 74 20 72  result set, it r
26b80 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
26b90 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33  OW]..**.** {H153
26ba0 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20 74  08}  If a call t
26bb0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
26bc0 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  S)] encounters a
26bd0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  n.**           [
26be0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
26bf0 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f  t | interrupt] o
26c00 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  r a run-time err
26c10 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  or,.**          
26c20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61   it returns an a
26c30 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
26c40 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f   code that is no
26c50 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20  t one of.**     
26c60 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b        [SQLITE_OK
26c70 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
26c80 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
26c90 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31 30  ]..**.** {H15310
26ca0 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65  }  If an [sqlite
26cb0 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e  3_interrupt | in
26cc0 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75  terrupt] or a ru
26cd0 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20  n-time error.** 
26ce0 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73            occurs
26cf0 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74   during a call t
26d00 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
26d10 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  S)].**          
26d20 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65 64   for a [prepared
26d30 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63 72   statement] S cr
26d40 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  eated using.**  
26d50 20 20 20 20 20 20 20 20 20 6c 65 67 61 63 79 20           legacy 
26d60 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
26d70 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
26d80 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  r.**           [
26d90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26da0 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  6()], then the f
26db0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
26dc0 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
26dd0 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
26de0 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  R], [SQLITE_BUSY
26df0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
26e00 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  SUSE]..*/.int sq
26e10 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
26e20 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
26e30 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
26e40 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
26e50 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b 48   a result set {H
26e60 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a  13770} <S10700>.
26e70 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68  **.** Returns th
26e80 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75  e number of valu
26e90 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  es in the curren
26ea0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
26eb0 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49  ult set..**.** I
26ec0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
26ed0 20 7b 48 31 33 37 37 31 7d 20 20 41 66 74 65 72   {H13771}  After
26ee0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
26ef0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61  te3_step(S)] tha
26f00 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  t returns [SQLIT
26f10 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20 20  E_ROW],.**      
26f20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
26f30 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d  3_data_count(S)]
26f40 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
26f50 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61  turn the same va
26f60 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lue.**          
26f70 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33   as the [sqlite3
26f80 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29  _column_count(S)
26f90 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ] function..**.*
26fa0 2a 20 7b 48 31 33 37 37 32 7d 20 20 41 66 74 65  * {H13772}  Afte
26fb0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
26fc0 53 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  S)] has returned
26fd0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
26fe0 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20   than.**        
26ff0 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20     [SQLITE_ROW] 
27000 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74  or before [sqlit
27010 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
27020 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 74  been called on t
27030 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  he.**           
27040 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27050 65 6e 74 5d 20 66 6f 72 20 74 68 65 20 66 69 72  ent] for the fir
27060 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20 69 74  st time since it
27070 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20   was.**         
27080 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
27090 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 6f  re | prepared] o
270a0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
270b0 20 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a 20 20 20   | reset],.**   
270c0 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
270d0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
270e0 53 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  S)] routine retu
270f0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74  rns zero..*/.int
27100 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
27110 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
27120 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
27130 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
27140 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
27150 20 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31   {H10265} <S1011
27160 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45  0><S10120>.** KE
27170 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
27180 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36  EXT.**.** {H1026
27190 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20 69  6} Every value i
271a0 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
271b0 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
271c0 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
271d0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
271e0 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
271f0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
27200 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
27210 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
27220 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
27230 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
27240 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
27250 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  /ul> {END}.**.**
27260 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
27270 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
27280 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
27290 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
272a0 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
272b0 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
272c0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
272d0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
272e0 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
272f0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
27300 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
27310 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
27320 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
27330 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
27340 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
27350 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
27360 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
27370 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
27380 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27390 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
273a0 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
273b0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
273c0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
273d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
273e0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
273f0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
27400 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
27410 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
27420 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
27430 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
27440 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
27450 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
27460 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
27470 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b  s From A Query {
27480 48 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e  H13800} <S10700>
27490 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
274a0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
274b0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
274c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
274d0 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
274e0 74 20 71 75 65 72 79 22 20 69 6e 74 65 72 66 61  t query" interfa
274f0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ce..**.** These 
27500 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
27510 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
27520 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
27530 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
27540 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
27550 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65  f a query.  In e
27560 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
27570 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
27580 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
27590 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
275a0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
275b0 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
275c0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
275d0 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
275e0 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
275f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27600 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
27610 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
27620 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
27630 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
27640 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
27650 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
27660 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
27670 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
27680 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  .  The leftmost 
27690 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
276a0 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
276b0 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20   index 0..**.** 
276c0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
276d0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
276e0 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
276f0 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
27700 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
27710 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
27720 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
27730 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
27740 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
27750 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
27760 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
27770 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
27780 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
27790 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
277a0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
277b0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
277c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
277d0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
277e0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
277f0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
27800 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
27810 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
27820 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
27830 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
27840 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
27850 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
27860 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
27870 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
27880 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
27890 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
278a0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
278b0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
278c0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
278d0 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
278e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
278f0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
27900 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
27910 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
27920 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
27930 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
27940 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
27950 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
27960 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
27970 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
27980 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
27990 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
279a0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
279b0 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
279c0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
279d0 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
279e0 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
279f0 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
27a00 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54  esult column.  T
27a10 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
27a20 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
27a30 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
27a40 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
27a50 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
27a60 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
27a70 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
27a80 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
27a90 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
27aa0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
27ab0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
27ac0 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
27ad0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
27ae0 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
27af0 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
27b00 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
27b10 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
27b20 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
27b30 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
27b40 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
27b50 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
27b60 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
27b70 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
27b80 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
27b90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27ba0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
27bb0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
27bc0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  sion..**.** If t
27bd0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
27be0 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
27bf0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
27c00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
27c10 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
27c20 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
27c30 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
27c40 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
27c50 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  g..** If the res
27c60 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
27c70 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
27c80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
27c90 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
27ca0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
27cb0 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
27cc0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
27cd0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20  of bytes..** If 
27ce0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
27cf0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
27d00 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
27d10 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
27d20 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
27d30 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
27d40 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
27d50 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
27d60 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
27d70 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
27d80 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
27d90 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72  ..** The value r
27da0 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
27db0 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
27dc0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20  o terminator at 
27dd0 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
27de0 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63  e string.  For c
27df0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
27e00 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68  e returned is th
27e10 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
27e20 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
27e30 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
27e40 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
27e50 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20  ..**.** Strings 
27e60 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
27e70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
27e80 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
27e90 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
27ea0 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
27eb0 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
27ec0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64   zero terminated
27ed0 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a  .  The return.**
27ee0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
27ef0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
27f00 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
27f10 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61  gth BLOB is an a
27f20 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e  rbitrary.** poin
27f30 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76  ter, possibly ev
27f40 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
27f50 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
27f60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
27f70 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73  s16() routine is
27f80 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69   similar to sqli
27f90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
27fa0 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73  ().** but leaves
27fb0 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55   the result in U
27fc0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20  TF-16 in native 
27fd0 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65  byte order inste
27fe0 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20  ad of UTF-8..** 
27ff0 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  The zero termina
28000 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75  tor is not inclu
28010 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e  ded in this coun
28020 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a  t..**.** The obj
28030 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
28040 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
28050 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
28060 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
28070 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
28080 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
28090 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
280a0 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
280b0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
280c0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
280d0 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
280e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
280f0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
28100 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
28110 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
28120 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
28130 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
28140 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
28150 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
28160 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
28170 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
28180 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
28190 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
281a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
281b0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
281c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
281d0 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
281e0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
281f0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
28200 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
28210 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
28220 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
28230 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
28240 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
28250 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
28260 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
28270 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
28280 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
28290 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
282a0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
282b0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
282c0 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
282d0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
282e0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
282f0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
28300 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
28310 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
28320 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
28330 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
28340 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
28350 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
28360 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
28370 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
28380 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
28390 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
283a0 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
283b0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
283c0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
283d0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
283e0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
283f0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
28400 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
28410 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
28420 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
28430 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
28440 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
28450 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
28460 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
28470 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
28480 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
28490 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
284a0 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
284b0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
284c0 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
284d0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
284e0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
284f0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
28500 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
28510 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
28520 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
28530 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
28540 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
28550 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
28560 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
28570 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
28580 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
28590 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
285a0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
285b0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
285c0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
285d0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
285e0 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
285f0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
28600 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
28610 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
28620 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
28630 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
28640 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
28650 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
28660 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
28670 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
28680 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
28690 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
286a0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
286b0 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
286c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
286d0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
286e0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
286f0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
28700 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
28710 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
28720 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
28730 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
28740 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
28750 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
28760 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
28770 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
28780 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
28790 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
287a0 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
287b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
287c0 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
287d0 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
287e0 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
287f0 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
28800 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
28810 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
28820 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
28830 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
28840 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
28850 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
28860 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
28870 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
28880 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
28890 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
288a0 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
288b0 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
288c0 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
288d0 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
288e0 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
288f0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
28900 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
28910 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
28920 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
28930 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
28940 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28950 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
28960 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
28970 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
28980 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
28990 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
289a0 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
289b0 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
289c0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
289d0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
289e0 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
289f0 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
28a00 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
28a10 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
28a20 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
28a30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
28a40 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
28a50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28a60 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
28a70 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
28a80 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
28a90 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
28aa0 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
28ab0 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
28ac0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
28ad0 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
28ae0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
28af0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
28b00 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
28b10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
28b20 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
28b30 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
28b40 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
28b50 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
28b60 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
28b70 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
28b80 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
28b90 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
28ba0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
28bb0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
28bc0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
28bd0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
28be0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
28bf0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
28c00 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
28c10 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76  </ul>.**.** Conv
28c20 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
28c30 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
28c40 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
28c50 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
28c60 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
28c70 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
28c80 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
28c90 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
28ca0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
28cb0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
28cc0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f  prior pointer po
28cd0 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76  ints to will hav
28ce0 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
28cf0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
28d00 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
28d10 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
28d20 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
28d30 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
28d40 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
28d50 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
28d60 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
28d70 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
28d80 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
28d90 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
28da0 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
28db0 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
28dc0 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
28dd0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
28de0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
28df0 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
28e00 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
28e10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28e20 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
28e30 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
28e40 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
28e50 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
28e60 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
28e70 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
28e80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
28e90 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
28ea0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
28eb0 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
28ec0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28ed0 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
28ee0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
28ef0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
28f00 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
28f10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
28f20 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
28f30 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
28f40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28f50 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
28f60 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
28f70 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
28f80 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
28f90 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
28fa0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
28fb0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
28fc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
28fd0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
28fe0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
28ff0 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
29000 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
29010 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
29020 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
29030 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
29040 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
29050 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
29060 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
29070 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
29080 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
29090 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
290a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
290b0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
290c0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72  * The pointers r
290d0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
290e0 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
290f0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
29100 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
29110 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
29120 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
29130 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
29140 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
29150 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
29160 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ] is called.  Th
29170 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
29180 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
29190 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
291a0 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
291b0 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
291c0 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
291d0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
291e0 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ed.** [sqlite3_c
291f0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
29200 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29210 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
29220 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
29230 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ee()]..**.** If 
29240 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
29250 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
29260 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
29270 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
29280 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
29290 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
292a0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
292b0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
292c0 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
292d0 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
292e0 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
292f0 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
29300 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
29310 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
29320 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
29330 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
29340 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
29350 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
29360 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
29370 2a 0a 2a 2a 20 7b 48 31 33 38 30 33 7d 20 54 68  *.** {H13803} Th
29380 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
29390 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74  n_blob(S,N)] int
293a0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
293b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
293c0 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
293d0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
293e0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
293f0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
29400 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
29410 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
29420 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 20  a BLOB and then 
29430 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20  returns a.**    
29440 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f        pointer to
29450 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76   the converted v
29460 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  alue..**.** {H13
29470 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  806} The [sqlite
29480 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53  3_column_bytes(S
29490 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
294a0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
294b0 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
294c0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c   bytes in the BL
294d0 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78  OB or string (ex
294e0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
294f0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
29500 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
29510 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
29520 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
29530 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
29540 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
29550 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
29560 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72  mn_blob(S,N)] or
29570 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
29580 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29590 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  t(S,N)]..**.** {
295a0 48 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c  H13809} The [sql
295b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
295c0 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  s16(S,N)] interf
295d0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ace returns the.
295e0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
295f0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
29600 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  he string (exclu
29610 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
29620 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
29630 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
29640 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
29650 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
29660 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
29670 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
29680 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29690 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a  text16(S,N)]..**
296a0 0a 2a 2a 20 7b 48 31 33 38 31 32 7d 20 54 68 65  .** {H13812} The
296b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
296c0 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e  _double(S,N)] in
296d0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
296e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
296f0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
29700 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
29710 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
29720 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
29730 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
29740 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
29750 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
29760 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20  t value and.**  
29770 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
29780 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76  a copy of that v
29790 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  alue..**.** {H13
297a0 38 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  815} The [sqlite
297b0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e  3_column_int(S,N
297c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
297d0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
297e0 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
297f0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
29800 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
29810 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a  t set for the.**
29820 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
29830 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
29840 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
29850 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
29860 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
29870 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20  turns the lower 
29880 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20  32 bits of that 
29890 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
298a0 48 31 33 38 31 38 7d 20 54 68 65 20 5b 73 71 6c  H13818} The [sql
298b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
298c0 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  4(S,N)] interfac
298d0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
298e0 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
298f0 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
29900 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
29910 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74  result set for t
29920 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
29930 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29940 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d  nt] S into a 64-
29950 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
29960 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  er and.**       
29970 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70     returns a cop
29980 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65  y of that intege
29990 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 31  r..**.** {H13821
299a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
299b0 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d  olumn_text(S,N)]
299c0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
299d0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
299e0 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
299f0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
29a00 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
29a10 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
29a20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65      the [prepare
29a30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
29a40 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
29a50 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20  nated UTF-8.**  
29a60 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
29a70 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
29a80 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
29a90 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  ing..**.** {H138
29aa0 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
29ab0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53  _column_text16(S
29ac0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
29ad0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
29ae0 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
29af0 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
29b00 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
29b10 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a  ult set for the.
29b20 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
29b30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29b40 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   S into a zero-t
29b50 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
29b60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69  .**          ali
29b70 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69  gned UTF-16 nati
29b80 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74  ve byte order st
29b90 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
29ba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70  .**          a p
29bb0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
29bc0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
29bd0 33 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  3827} The [sqlit
29be0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53  e3_column_type(S
29bf0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
29c00 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
29c10 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54     one of [SQLIT
29c20 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_NULL], [SQLITE
29c30 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49  _INTEGER], [SQLI
29c40 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20  TE_FLOAT],.**   
29c50 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
29c60 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  EXT], or [SQLITE
29c70 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70  _BLOB] as approp
29c80 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20  riate for.**    
29c90 20 20 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f        the Nth co
29ca0 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
29cb0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
29cc0 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
29cd0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70            the [p
29ce0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29cf0 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  t] S..**.** {H13
29d00 38 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  830} The [sqlite
29d10 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53  3_column_value(S
29d20 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
29d30 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20  eturns a.**     
29d40 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20       pointer to 
29d50 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
29d60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
29d70 62 6a 65 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a  bject for the.**
29d80 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
29d90 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
29da0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
29db0 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
29dc0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70            the [p
29dd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29de0 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  t] S..*/.const v
29df0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
29e00 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
29e10 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
29e20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
29e30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
29e40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
29e50 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
29e60 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
29e70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29e80 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
29e90 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
29ea0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
29eb0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
29ec0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
29ed0 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
29ee0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
29ef0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
29f00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29f10 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
29f20 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
29f30 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
29f40 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
29f50 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
29f60 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
29f70 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
29f80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29f90 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
29fa0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
29fb0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
29fc0 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
29fd0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
29fe0 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
29ff0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2a000 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
2a010 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
2a020 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a030 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
2a040 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2a050 65 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 37  ect {H13300} <S7
2a060 30 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a  0300><S30100>.**
2a070 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2a080 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
2a090 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
2a0a0 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
2a0b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2a0c0 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  ** If the statem
2a0d0 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65 64  ent was executed
2a0e0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72   successfully or
2a0f0 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74   not executed at
2a100 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51   all, then.** SQ
2a110 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72  LITE_OK is retur
2a120 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74 69 6f  ned. If executio
2a130 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65  n of the stateme
2a140 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61  nt failed then a
2a150 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
2a160 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
2a170 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2a180 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
2a190 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
2a1a0 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
2a1b0 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65  point during the
2a1c0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
2a1d0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2a1e0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74  tatement].  If t
2a1f0 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69  he virtual machi
2a200 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f  ne has not.** co
2a210 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
2a220 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74  n when this rout
2a230 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  ine is called, t
2a240 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65  hat is like.** e
2a250 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65  ncountering an e
2a260 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  rror or an [sqli
2a270 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20  te3_interrupt | 
2a280 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49  interrupt]..** I
2a290 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65  ncomplete update
2a2a0 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20  s may be rolled 
2a2b0 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63  back and transac
2a2c0 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a  tions canceled,.
2a2d0 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ** depending on 
2a2e0 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  the circumstance
2a2f0 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65  s, and the.** [e
2a300 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72  rror code] retur
2a310 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c  ned will be [SQL
2a320 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a  ITE_ABORT]..**.*
2a330 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2a340 0a 2a 2a 20 7b 48 31 31 33 30 32 7d 20 54 68 65  .** {H11302} The
2a350 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2a360 7a 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  ze(S)] interface
2a370 20 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a   destroys the.**
2a380 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
2a390 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2a3a0 20 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61 6c   and releases al
2a3b0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65  l.**          me
2a3c0 6d 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72 65  mory and file re
2a3d0 73 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79 20  sources held by 
2a3e0 74 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  that object..**.
2a3f0 2a 2a 20 7b 48 31 31 33 30 34 7d 20 49 66 20 74  ** {H11304} If t
2a400 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2a410 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2a420 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
2a430 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2a440 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a450 5d 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e 20  ] S returned an 
2a460 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20  error,.**       
2a470 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
2a480 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65  _finalize(S)] re
2a490 74 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65 20  turns that same 
2a4a0 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  error..*/.int sq
2a4b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
2a4c0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2a4d0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2a4e0 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
2a4f0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2a500 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 33 30 7d   Object {H13330}
2a510 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70300>.**.** 
2a520 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
2a530 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
2a540 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
2a550 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2a560 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
2a570 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
2a580 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
2a590 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
2a5a0 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20  ted..** Any SQL 
2a5b0 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
2a5c0 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
2a5d0 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
2a5e0 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
2a5f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2a600 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
2a610 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
2a620 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
2a630 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
2a640 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
2a650 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
2a660 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ndings..**.** {H
2a670 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c 69  11332} The [sqli
2a680 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
2a690 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
2a6a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2a6b0 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20  tement] S.**    
2a6c0 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74 68        back to th
2a6d0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
2a6e0 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
2a6f0 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 20 74 68  * {H11334} If th
2a700 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2a710 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2a720 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2a730 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
2a740 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a750 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
2a760 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
2a770 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20  ITE_DONE],.**   
2a780 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71         or if [sq
2a790 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
2a7a0 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
2a7b0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
2a7c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
2a7d0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
2a7e0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
2a7f0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
2a800 20 7b 48 31 31 33 33 36 7d 20 49 66 20 74 68 65   {H11336} If the
2a810 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2a820 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2a830 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
2a840 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2a850 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a860 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
2a870 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  rror, then.**   
2a880 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2a890 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
2a8a0 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
2a8b0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
2a8c0 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54 68  *.** {H11338} Th
2a8d0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2a8e0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
2a8f0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
2a900 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  he values.**    
2a910 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71        of any [sq
2a920 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2a930 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
2a940 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a950 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
2a960 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
2a970 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2a980 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2a990 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
2a9a0 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
2a9b0 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c  tions {H16100} <
2a9c0 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S20200>.** KEYWO
2a9d0 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
2a9e0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2a9f0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2aa00 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2aa10 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2aa20 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2aa30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2aa40 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2aa50 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74  s}.**.** These t
2aa60 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  wo functions (co
2aa70 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
2aa80 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
2aa90 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
2aaa0 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
2aab0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
2aac0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2aad0 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
2aae0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2aaf0 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
2ab00 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
2ab10 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
2ab20 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 65  ly difference be
2ab30 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f  tween the.** two
2ab40 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63   is that the sec
2ab50 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ond parameter, t
2ab60 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28  he name of the (
2ab70 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e  scalar) function
2ab80 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2ab90 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20  , is encoded in 
2aba0 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65  UTF-8 for sqlite
2abb0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2abc0 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a  n() and UTF-16.*
2abd0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
2abe0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2abf0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  )..**.** The fir
2ac00 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2ac10 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2ac20 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
2ac30 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
2ac40 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
2ac50 61 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e  added.  If a sin
2ac60 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65 73  gle program uses
2ac70 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
2ac80 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2ac90 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79  ction internally
2aca0 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 74  , then SQL funct
2acb0 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
2acc0 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20  ed individually 
2acd0 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62  to.** each datab
2ace0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  ase connection..
2acf0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
2ad00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2ad10 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
2ad20 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
2ad30 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
2ad40 65 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 6c  edefined.  The l
2ad50 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
2ad60 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
2ad70 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75  255 bytes, exclu
2ad80 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a  sive of.** the z
2ad90 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
2ada0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e   Note that the n
2adb0 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  ame length limit
2adc0 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f   is in bytes, no
2add0 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e  t.** characters.
2ade0 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f    Any attempt to
2adf0 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
2ae00 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
2ae10 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
2ae20 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
2ae30 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74  ERROR] being ret
2ae40 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
2ae50 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2ae60 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2ae70 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
2ae80 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2ae90 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2aea0 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73  e takes. If this
2aeb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
2aec0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
2aed0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2aee0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
2aef0 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
2af00 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a  r of arguments..
2af10 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  **.** The fourth
2af20 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
2af30 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
2af40 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
2af50 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
2af60 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
2af70 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
2af80 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
2af90 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20  eters.  Any SQL 
2afa0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2afb0 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  ntation should b
2afc0 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
2afd0 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d  * work with UTF-
2afe0 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20  8, UTF-16le, or 
2aff0 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73  UTF-16be.  But s
2b000 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ome implementati
2b010 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f  ons may be.** mo
2b020 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74  re efficient wit
2b030 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74  h one encoding t
2b040 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74  han another.  It
2b050 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a   is allowed to.*
2b060 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
2b070 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2b080 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
2b090 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2b0a0 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
2b0b0 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
2b0c0 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
2b0d0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
2b0e0 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
2b0f0 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70  ..** When multip
2b100 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2b110 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
2b120 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
2b130 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
2b140 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
2b150 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
2b160 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
2b170 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
2b180 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72  sion..** If ther
2b190 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67  e is only a sing
2b1a0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2b1b0 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74  n which does not
2b1c0 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a   care what text.
2b1d0 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  ** encoding is u
2b1e0 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  sed, then the fo
2b1f0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68  urth argument sh
2b200 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f  ould be [SQLITE_
2b210 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ANY]..**.** The 
2b220 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
2b230 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
2b240 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
2b250 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2b260 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
2b270 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
2b280 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
2b290 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
2b2a0 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a  ser_data()]..**.
2b2b0 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20  ** The seventh, 
2b2c0 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68  eighth and ninth
2b2d0 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
2b2e0 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
2b2f0 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
2b300 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
2b310 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
2b320 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2b330 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2b340 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41  .** aggregate. A
2b350 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2b360 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
2b370 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2b380 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
2b390 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e  callback only, N
2b3a0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f  ULL pointers sho
2b3b0 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73  uld be passed as
2b3c0 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
2b3d0 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
2b3e0 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74  ers. An aggregat
2b3f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
2b400 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
2b410 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
2b420 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
2b430 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64   and NULL should
2b440 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
2b450 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20  Func. To delete 
2b460 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53  an existing.** S
2b470 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
2b480 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e  ggregate, pass N
2b490 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ULL for all thre
2b4a0 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  e function callb
2b4b0 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  acks..**.** It i
2b4c0 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
2b4d0 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
2b4e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2b4f0 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
2b500 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
2b510 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
2b520 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
2b530 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
2b540 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
2b550 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
2b560 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2b570 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69  ings.  SQLite wi
2b580 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
2b590 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73  plementation mos
2b5a0 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
2b5b0 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
2b5c0 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
2b5d0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  nction is used..
2b5e0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2b5f0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 33 7d  :.**.** {H16103}
2b600 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   The [sqlite3_cr
2b610 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2b620 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 68  )] interface beh
2b630 61 76 65 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20  aves exactly.** 
2b640 20 20 20 20 20 20 20 20 20 6c 69 6b 65 20 5b 73           like [s
2b650 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2b660 6e 63 74 69 6f 6e 28 29 5d 20 69 6e 20 65 76 65  nction()] in eve
2b670 72 79 20 77 61 79 20 65 78 63 65 70 74 20 74 68  ry way except th
2b680 61 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 20  at it.**        
2b690 20 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65    interprets the
2b6a0 20 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 20 61   zFunctionName a
2b6b0 72 67 75 6d 65 6e 74 20 61 73 20 7a 65 72 6f 2d  rgument as zero-
2b6c0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31  terminated UTF-1
2b6d0 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61  6.**          na
2b6e0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
2b6f0 69 6e 73 74 65 61 64 20 6f 66 20 61 73 20 7a 65  instead of as ze
2b700 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2b710 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  F-8..**.** {H161
2b720 30 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  06} A successful
2b730 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
2b740 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
2b750 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2b760 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
2b770 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
2b780 72 65 67 69 73 74 65 72 73 0a 2a 2a 20 20 20 20  registers.**    
2b790 20 20 20 20 20 20 6f 72 20 72 65 70 6c 61 63 65        or replace
2b7a0 73 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  s callback funct
2b7b0 69 6f 6e 73 20 69 6e 20 74 68 65 20 5b 64 61 74  ions in the [dat
2b7c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b7d0 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ] D.**          
2b7e0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
2b7f0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2b800 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20  on named X with 
2b810 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  N parameters.** 
2b820 20 20 20 20 20 20 20 20 20 61 6e 64 20 68 61 76           and hav
2b830 69 6e 67 20 61 20 70 72 65 66 65 72 72 65 64 20  ing a preferred 
2b840 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66  text encoding of
2b850 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30   E..**.** {H1610
2b860 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  9} A successful 
2b870 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2b880 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2b890 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
2b8a0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  )].**          r
2b8b0 65 70 6c 61 63 65 73 20 74 68 65 20 50 2c 20 46  eplaces the P, F
2b8c0 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65  , S, and L value
2b8d0 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72  s from any prior
2b8e0 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20   calls with.**  
2b8f0 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
2b900 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20   D, X, N, and E 
2b910 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  values..**.** {H
2b920 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  16112} The [sqli
2b930 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2b940 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e  ion(D,X,...)] in
2b950 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
2b960 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  th.**          a
2b970 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20   return code of 
2b980 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
2b990 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2b9a0 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20  on name X is.** 
2b9b0 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20           longer 
2b9c0 74 68 61 6e 20 32 35 35 20 62 79 74 65 73 20 65  than 255 bytes e
2b9d0 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
2b9e0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2b9f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 38 7d 20  .**.** {H16118} 
2ba00 45 69 74 68 65 72 20 46 20 6d 75 73 74 20 62 65  Either F must be
2ba10 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20   NULL and S and 
2ba20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f  L are non-NULL o
2ba30 72 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20 20  r else F.**     
2ba40 20 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c       is non-NULL
2ba50 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65   and S and L are
2ba60 20 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73 65   NULL, otherwise
2ba70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2ba80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ba90 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
2baa0 46 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73 20  F,S,L)] returns 
2bab0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a  [SQLITE_ERROR]..
2bac0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 31 7d 20 54  **.** {H16121} T
2bad0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2bae0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e  te_function(D,..
2baf0 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61  .)] interface fa
2bb00 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20  ils with an.**  
2bb10 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f          error co
2bb20 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55  de of [SQLITE_BU
2bb30 53 59 5d 20 69 66 20 74 68 65 72 65 20 65 78 69  SY] if there exi
2bb40 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  st [prepared sta
2bb50 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20  tements].**     
2bb60 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 20       associated 
2bb70 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
2bb80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2bb90 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 34 7d  ..**.** {H16124}
2bba0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   The [sqlite3_cr
2bbb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2bbc0 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  X,N,...)] interf
2bbd0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61  ace fails with a
2bbe0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72  n.**          er
2bbf0 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
2bc00 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 61  ITE_ERROR] if pa
2bc10 72 61 6d 65 74 65 72 20 4e 20 28 73 70 65 63 69  rameter N (speci
2bc20 66 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72  fying the number
2bc30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
2bc40 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
2bc50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62 65   SQL function be
2bc60 69 6e 67 20 72 65 67 69 73 74 65 72 65 64 29 20  ing registered) 
2bc70 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20  is less.**      
2bc80 20 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67      than -1 or g
2bc90 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e  reater than 127.
2bca0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 37 7d 20  .**.** {H16127} 
2bcb0 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  When N is non-ne
2bcc0 67 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c  gative, the [sql
2bcd0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2bce0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
2bcf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
2bd00 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61  erface causes ca
2bd10 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e  llbacks to be in
2bd20 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51  voked for the SQ
2bd30 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
2bd40 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77         named X w
2bd50 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  hen the number o
2bd60 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  f arguments to t
2bd70 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2bd80 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  is.**          e
2bd90 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20  xactly N..**.** 
2bda0 7b 48 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20  {H16130} When N 
2bdb0 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69  is -1, the [sqli
2bdc0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2bdd0 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a  ion(D,X,N,...)].
2bde0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
2bdf0 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c  rface causes cal
2be00 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76  lbacks to be inv
2be10 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c  oked for the SQL
2be20 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2be30 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 69        named X wi
2be40 74 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  th any number of
2be50 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
2be60 2a 20 7b 48 31 36 31 33 33 7d 20 57 68 65 6e 20  * {H16133} When 
2be70 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2be80 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2be90 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a  n(D,X,N,...)].**
2bea0 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66            specif
2beb0 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  y multiple imple
2bec0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2bed0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2bee0 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  X.**          an
2bef0 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65  d when one imple
2bf00 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e  mentation has N>
2bf10 3d 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  =0 and the other
2bf20 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20   has N=(-1).**  
2bf30 20 20 20 20 20 20 20 20 74 68 65 20 69 6d 70 6c          the impl
2bf40 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
2bf50 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73 20  a non-zero N is 
2bf60 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a  preferred..**.**
2bf70 20 7b 48 31 36 31 33 36 7d 20 57 68 65 6e 20 63   {H16136} When c
2bf80 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2bf90 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2bfa0 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a  (D,X,N,E,...)].*
2bfb0 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69  *          speci
2bfc0 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  fy multiple impl
2bfd0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2bfe0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2bff0 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20   X with.**      
2c000 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75 6d      the same num
2c010 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
2c020 20 4e 20 62 75 74 20 77 69 74 68 20 64 69 66 66   N but with diff
2c030 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  erent.**        
2c040 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74    encodings E, t
2c050 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  hen the implemen
2c060 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20 6d  tation where E m
2c070 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 20  atches the.**   
2c080 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20         database 
2c090 65 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 65 66  encoding is pref
2c0a0 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  erred..**.** {H1
2c0b0 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67  6139} For an agg
2c0c0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2c0d0 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e  ion created usin
2c0e0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
2c0f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2c100 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
2c110 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e  ,0,S,L)] the fin
2c120 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20  alizer.**       
2c130 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 77 69     function L wi
2c140 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e 76  ll always be inv
2c150 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  oked exactly onc
2c160 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e if the.**     
2c170 20 20 20 20 20 73 74 65 70 20 66 75 6e 63 74 69       step functi
2c180 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20 6f  on S is called o
2c190 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
2c1a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 34 32 7d  ..**.** {H16142}
2c1b0 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
2c1c0 6f 6b 65 73 20 65 69 74 68 65 72 20 74 68 65 20  okes either the 
2c1d0 78 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20 66  xFunc or xStep f
2c1e0 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20  unction of.**   
2c1f0 20 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69 63         an applic
2c200 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2c210 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
2c220 67 72 65 67 61 74 65 20 63 72 65 61 74 65 64 0a  gregate created.
2c230 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b  **          by [
2c240 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2c250 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b 73  unction()] or [s
2c260 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2c270 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20  nction16()],.** 
2c280 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68           then th
2c290 65 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c 69  e array of [sqli
2c2a0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2c2b0 74 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ts passed as the
2c2c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 69  .**          thi
2c2d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  rd parameter are
2c2e0 20 61 6c 77 61 79 73 20 5b 70 72 6f 74 65 63 74   always [protect
2c2f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c300 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e  ] objects..*/.in
2c310 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2c320 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
2c330 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
2c340 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
2c350 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
2c360 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
2c370 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
2c380 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
2c390 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2c3a0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2c3b0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2c3c0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
2c3d0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2c3e0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2c3f0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
2c400 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c410 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2c420 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c430 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
2c440 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
2c450 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
2c460 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
2c470 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
2c480 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
2c490 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
2c4a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2c4b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2c4c0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
2c4d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2c4e0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2c4f0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2c500 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
2c510 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f  _context*).);../
2c520 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
2c530 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48  ext Encodings {H
2c540 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e 20  10267} <S50200> 
2c550 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H16100>.**.** T
2c560 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
2c570 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
2c580 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
2c590 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
2c5a0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
2c5b0 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
2c5c0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
2c5d0 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
2c5e0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
2c5f0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
2c600 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
2c610 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
2c620 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
2c630 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
2c640 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
2c650 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
2c660 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
2c670 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
2c680 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
2c690 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c6a0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
2c6b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2c6c0 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
2c6d0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
2c6e0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
2c6f0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
2c700 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75  REF: Obsolete Fu
2c710 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
2c720 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
2c730 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65  e all now obsole
2c740 74 65 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  te.  In order to
2c750 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
2c760 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
2c770 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
2c780 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75  code, we continu
2c790 65 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20  e to support.** 
2c7a0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
2c7b0 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 64    However, new d
2c7c0 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65  evelopment proje
2c7d0 63 74 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  cts should avoid
2c7e0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
2c7f0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
2c800 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
2c810 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
2c820 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
2c830 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
2c840 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
2c850 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74   tell you want t
2c860 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73  hey do..*/.int s
2c870 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2c880 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
2c890 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71  ontext*);.int sq
2c8a0 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
2c8b0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e  lite3_stmt*);.in
2c8c0 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
2c8d0 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
2c8e0 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
2c8f0 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73  e3_stmt*);.int s
2c900 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
2c910 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69  cover(void);.voi
2c920 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
2c930 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
2c940 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
2c950 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
2c960 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
2c970 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c  nt64,int),void*,
2c980 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2c990 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c9a0 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
2c9b0 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
2c9c0 72 20 56 61 6c 75 65 73 20 7b 48 31 35 31 30 30  r Values {H15100
2c9d0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20200>.**.**
2c9e0 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
2c9f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2ca00 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
2ca10 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
2ca20 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
2ca30 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
2ca40 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
2ca50 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
2ca60 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
2ca70 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
2ca80 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
2ca90 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
2caa0 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
2cab0 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
2cac0 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
2cad0 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
2cae0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2caf0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2cb00 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2cb10 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
2cb20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
2cb30 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
2cb40 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2cb50 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
2cb60 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2cb70 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
2cb80 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
2cb90 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
2cba0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2cbb0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2cbc0 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
2cbd0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2cbe0 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
2cbf0 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
2cc00 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
2cc10 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
2cc20 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
2cc30 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
2cc40 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
2cc50 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2cc60 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
2cc70 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
2cc80 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
2cc90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2cca0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
2ccb0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
2ccc0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2ccd0 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
2cce0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2ccf0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
2cd00 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
2cd10 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
2cd20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2cd30 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
2cd40 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2cd50 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
2cd60 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
2cd70 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65  cept that  these
2cd80 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
2cd90 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
2cda0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2cdb0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
2cdc0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
2cdd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
2cde0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
2cdf0 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
2ce00 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  umber..**.** The
2ce10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2ce20 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
2ce30 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
2ce40 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
2ce50 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
2ce60 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
2ce70 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65  st machine.  The
2ce80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2ce90 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
2cea0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2ceb0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
2cec0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
2ced0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
2cee0 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
2cef0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
2cf00 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
2cf10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
2cf20 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2cf30 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
2cf40 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
2cf50 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
2cf60 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
2cf70 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
2cf80 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
2cf90 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
2cfa0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
2cfb0 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
2cfc0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
2cfd0 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
2cfe0 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
2cff0 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
2d000 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
2d010 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
2d020 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
2d030 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
2d040 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
2d050 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
2d060 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
2d070 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
2d080 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
2d090 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
2d0a0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
2d0b0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
2d0c0 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
2d0d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2d0e0 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
2d0f0 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
2d100 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
2d110 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
2d120 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
2d130 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
2d140 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
2d150 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2d160 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
2d170 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
2d180 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
2d190 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
2d1a0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2d1b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2d1c0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
2d1d0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
2d1e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2d1f0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2d200 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d210 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
2d220 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2d230 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2d240 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2d250 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
2d260 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
2d270 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
2d280 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
2d290 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  rameters..**.** 
2d2a0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2d2b0 2a 20 7b 48 31 35 31 30 33 7d 20 54 68 65 20 5b  * {H15103} The [
2d2c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2d2d0 6f 62 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  ob(V)] interface
2d2e0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2d2f0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2d300 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2d310 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2d320 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65  o a BLOB and the
2d330 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  n.**          re
2d340 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2d350 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64  to the converted
2d360 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48   value..**.** {H
2d370 31 35 31 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  15106} The [sqli
2d380 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2d390 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  V)] interface re
2d3a0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
2d3b0 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
2d3c0 62 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f  bytes in the BLO
2d3d0 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63  B or string (exc
2d3e0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
2d3f0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
2d400 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
2d410 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
2d420 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
2d430 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
2d440 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2d450 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  o [sqlite3_value
2d460 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20  _blob(V)] or.** 
2d470 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2d480 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d  3_value_text(V)]
2d490 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 39 7d  ..**.** {H15109}
2d4a0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2d4b0 6c 75 65 5f 62 79 74 65 73 31 36 28 56 29 5d 20  lue_bytes16(V)] 
2d4c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2d4d0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2d4e0 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
2d4f0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  s in the string 
2d500 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
2d510 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
2d520 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
2d530 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
2d540 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
2d550 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
2d560 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
2d570 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76  ll to [sqlite3_v
2d580 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 2c  alue_text16(V)],
2d590 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2d5a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2d5b0 31 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71  16be(V)], or [sq
2d5c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2d5d0 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16le(V)]..**.** 
2d5e0 7b 48 31 35 31 31 32 7d 20 54 68 65 20 5b 73 71  {H15112} The [sq
2d5f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
2d600 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  le(V)] interface
2d610 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2d620 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2d630 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2d640 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2d650 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  o a floating poi
2d660 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20  nt value and.** 
2d670 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
2d680 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
2d690 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  value..**.** {H1
2d6a0 35 31 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  5115} The [sqlit
2d6b0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d  e3_value_int(V)]
2d6c0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2d6d0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2d6e0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2d6f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2d700 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34  ject V into a 64
2d710 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2d720 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
2d730 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20      returns the 
2d740 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66  lower 32 bits of
2d750 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
2d760 2a 0a 2a 2a 20 7b 48 31 35 31 31 38 7d 20 54 68  *.** {H15118} Th
2d770 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2d780 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65 72  _int64(V)] inter
2d790 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2d7a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2d7b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d7c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2d7d0 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
2d7e0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
2d7f0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
2d800 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
2d810 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  that integer..**
2d820 0a 2a 2a 20 7b 48 31 35 31 32 31 7d 20 54 68 65  .** {H15121} The
2d830 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d840 74 65 78 74 28 56 29 5d 20 69 6e 74 65 72 66 61  text(V)] interfa
2d850 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2d860 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
2d870 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d880 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
2d890 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
2d8a0 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20  nated UTF-8.**  
2d8b0 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
2d8c0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2d8d0 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
2d8e0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  ing..**.** {H151
2d8f0 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
2d900 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29  _value_text16(V)
2d910 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2d920 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2d930 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2d940 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d950 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a  bject V into a z
2d960 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32  ero-terminated 2
2d970 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  -byte.**        
2d980 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36    aligned UTF-16
2d990 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2d9a0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  er.**          s
2d9b0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2d9c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2d9d0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  hat string..**.*
2d9e0 2a 20 7b 48 31 35 31 32 37 7d 20 54 68 65 20 5b  * {H15127} The [
2d9f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2da00 78 74 31 36 62 65 28 56 29 5d 20 69 6e 74 65 72  xt16be(V)] inter
2da10 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2da20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2da30 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2da40 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2da50 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
2da60 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
2da70 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
2da80 65 64 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  ed UTF-16 big-en
2da90 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
2daa0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2dab0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2dac0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2dad0 0a 2a 2a 20 7b 48 31 35 31 33 30 7d 20 54 68 65  .** {H15130} The
2dae0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2daf0 74 65 78 74 31 36 6c 65 28 56 29 5d 20 69 6e 74  text16le(V)] int
2db00 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2db10 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2db20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2db30 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2db40 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
2db50 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
2db60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69  .**          ali
2db70 67 6e 65 64 20 55 54 46 2d 31 36 20 6c 69 74 74  gned UTF-16 litt
2db80 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  le-endian.**    
2db90 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
2dba0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2dbb0 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
2dbc0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 33  g..**.** {H15133
2dbd0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2dbe0 61 6c 75 65 5f 74 79 70 65 28 56 29 5d 20 69 6e  alue_type(V)] in
2dbf0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
2dc00 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20  **          one 
2dc10 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  of [SQLITE_NULL]
2dc20 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  , [SQLITE_INTEGE
2dc30 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  R], [SQLITE_FLOA
2dc40 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  T],.**          
2dc50 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f  [SQLITE_TEXT], o
2dc60 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20  r [SQLITE_BLOB] 
2dc70 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  as appropriate f
2dc80 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
2dc90 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2dca0 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a  e] object V..**.
2dcb0 2a 2a 20 7b 48 31 35 31 33 36 7d 20 54 68 65 20  ** {H15136} The 
2dcc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e  [sqlite3_value_n
2dcd0 75 6d 65 72 69 63 5f 74 79 70 65 28 56 29 5d 20  umeric_type(V)] 
2dce0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2dcf0 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ts.**          t
2dd00 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  he [protected sq
2dd10 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2dd20 65 63 74 20 56 20 69 6e 74 6f 20 65 69 74 68 65  ect V into eithe
2dd30 72 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a  r an integer or.
2dd40 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 6c  **          a fl
2dd50 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2dd60 75 65 20 69 66 20 69 74 20 63 61 6e 20 64 6f 20  ue if it can do 
2dd70 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  so without loss 
2dd80 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  of.**          i
2dd90 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20  nformation, and 
2dda0 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b  returns one of [
2ddb0 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a  SQLITE_NULL],.**
2ddc0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2ddd0 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c  E_INTEGER], [SQL
2dde0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
2ddf0 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a  ITE_TEXT], or.**
2de00 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2de10 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f  E_BLOB] as appro
2de20 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 0a 2a  priate for the.*
2de30 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2de40 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2de50 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 61 66  lue] object V af
2de60 74 65 72 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ter the conversi
2de70 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63  on attempt..*/.c
2de80 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2de90 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
2dea0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2deb0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2dec0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
2ded0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2dee0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2def0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
2df00 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
2df10 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
2df20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2df30 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2df40 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
2df50 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
2df60 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
2df70 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
2df80 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2df90 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2dfa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2dfb0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
2dfc0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2dfd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2dfe0 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
2dff0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
2e000 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2e010 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2e020 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
2e030 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2e040 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
2e050 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2e060 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2e070 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2e080 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2e090 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
2e0a0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2e0b0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
2e0c0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
2e0d0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
2e0e0 43 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 30 7d  Context {H16210}
2e0f0 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
2e100 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
2e110 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 20  on of aggregate 
2e120 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  SQL functions us
2e130 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
2e140 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20  o allocate.** a 
2e150 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74  structure for st
2e160 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
2e170 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
2e180 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
2e190 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2e1a0 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20  ntext() routine 
2e1b0 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a  is called for a.
2e1c0 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 61 67  ** particular ag
2e1d0 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20  gregate, SQLite 
2e1e0 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73  allocates nBytes
2e1f0 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
2e200 65 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d  es out that.** m
2e210 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
2e220 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2e230 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  it. On second an
2e240 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
2e250 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
2e260 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2e270 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
2e280 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2e290 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74  tion index,.** t
2e2a0 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
2e2b0 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 20  s returned. The 
2e2c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2e2d0 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
2e2e0 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20 72  can use.** the r
2e2f0 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74  eturned buffer t
2e300 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74  o accumulate dat
2e310 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  a..**.** SQLite 
2e320 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
2e330 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  ees the allocate
2e340 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74 68  d buffer when th
2e350 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71  e aggregate.** q
2e360 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
2e370 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2e380 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
2e390 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
2e3a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
2e3b0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
2e3c0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
2e3d0 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
2e3e0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
2e3f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  the callback rou
2e400 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
2e410 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
2e420 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  te function..**.
2e430 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2e440 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2e450 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2e460 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2e470 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
2e480 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
2e490 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  nning..**.** INV
2e4a0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2e4b0 48 31 36 32 31 31 7d 20 54 68 65 20 66 69 72 73  H16211} The firs
2e4c0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  t invocation of 
2e4d0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2e4e0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
2e4f0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
2e500 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e   a particular in
2e510 73 74 61 6e 63 65 20 6f 66 20 61 6e 20 61 67 67  stance of an agg
2e520 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2e530 28 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61  (for a particula
2e540 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  r.**          co
2e550 6e 74 65 78 74 20 43 29 20 63 61 75 73 65 73 20  ntext C) causes 
2e560 53 51 4c 69 74 65 20 74 6f 20 61 6c 6c 6f 63 61  SQLite to alloca
2e570 74 65 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  te N bytes of me
2e580 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20 20 20 20 20  mory,.**        
2e590 20 20 7a 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f    zero that memo
2e5a0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 61  ry, and return a
2e5b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2e5c0 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79  allocated memory
2e5d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 33 7d  ..**.** {H16213}
2e5e0 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   If a memory all
2e5f0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
2e600 63 75 72 73 20 64 75 72 69 6e 67 0a 2a 2a 20 20  curs during.**  
2e610 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2e620 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2e630 78 74 28 43 2c 4e 29 5d 20 74 68 65 6e 20 74 68  xt(C,N)] then th
2e640 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
2e650 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ns 0..**.** {H16
2e660 32 31 35 7d 20 53 65 63 6f 6e 64 20 61 6e 64 20  215} Second and 
2e670 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2e680 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20 20  ations of.**    
2e690 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61        [sqlite3_a
2e6a0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2e6b0 28 43 2c 4e 29 5d 20 66 6f 72 20 74 68 65 20 73  (C,N)] for the s
2e6c0 61 6d 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  ame context poin
2e6d0 74 65 72 20 43 0a 2a 2a 20 20 20 20 20 20 20 20  ter C.**        
2e6e0 20 20 69 67 6e 6f 72 65 20 74 68 65 20 4e 20 70    ignore the N p
2e6f0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
2e700 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  urn a pointer to
2e710 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
2e720 20 20 20 20 20 20 62 6c 6f 63 6b 20 6f 66 20 6d        block of m
2e730 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
2e740 79 20 74 68 65 20 66 69 72 73 74 20 69 6e 76 6f  y the first invo
2e750 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  cation..**.** {H
2e760 31 36 32 31 37 7d 20 54 68 65 20 6d 65 6d 6f 72  16217} The memor
2e770 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b  y allocated by [
2e780 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2e790 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20  e_context(C,N)] 
2e7a0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  is.**          a
2e7b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2e7c0 65 64 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 63  ed on the next c
2e7d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2e7e0 72 65 73 65 74 28 29 5d 0a 2a 2a 20 20 20 20 20  reset()].**     
2e7f0 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
2e800 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 66 6f 72  _finalize()] for
2e810 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2e820 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e 74 61 69  tatement] contai
2e830 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ning.**         
2e840 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66   the aggregate f
2e850 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74  unction associat
2e860 65 64 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20  ed with context 
2e870 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  C..*/.void *sqli
2e880 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2e890 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
2e8a0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
2e8b0 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
2e8c0 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
2e8d0 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48  For Functions {H
2e8e0 31 36 32 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a  16240} <S20200>.
2e8f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2e900 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
2e910 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2e920 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
2e930 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
2e940 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
2e950 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
2e960 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
2e970 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2e980 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2e990 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2e9a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2e9b0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
2e9c0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
2e9d0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
2e9e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2e9f0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2ea00 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
2ea10 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
2ea20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2ea30 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2ea40 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
2ea50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2ea60 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
2ea70 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e  unning..**.** IN
2ea80 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2ea90 7b 48 31 36 32 34 33 7d 20 54 68 65 20 5b 73 71  {H16243} The [sq
2eaa0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2eab0 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  C)] interface re
2eac0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
2ead0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2eae0 50 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74  P pointer from t
2eaf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2eb00 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2eb10 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a  N,E,P,F,S,L)].**
2eb20 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
2eb30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2eb40 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c  ction16(D,X,N,E,
2eb50 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74  P,F,S,L)] call t
2eb60 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
2eb70 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 53  registered the S
2eb80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f  QL function asso
2eb90 63 69 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c  ciated with [sql
2eba0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e  ite3_context] C.
2ebb0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2ebc0 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
2ebd0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
2ebe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ebf0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2ec00 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
2ec10 73 20 7b 48 31 36 32 35 30 7d 20 3c 53 36 30 36  s {H16250} <S606
2ec20 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a  00><S20200>.**.*
2ec30 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
2ec40 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2ec50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2ec60 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2ec70 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
2ec80 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2ec90 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
2eca0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
2ecb0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2ecc0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2ecd0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2ece0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ecf0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
2ed00 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
2ed10 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
2ed20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2ed30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2ed40 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2ed50 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 35  TS:.**.** {H1625
2ed60 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2ed70 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
2ed80 65 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(C)] interface 
2ed90 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2eda0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2edb0 20 20 44 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d    D pointer from
2edc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2edd0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2ede0 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a  X,N,E,P,F,S,L)].
2edf0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
2ee00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2ee10 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c  unction16(D,X,N,
2ee20 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c  E,P,F,S,L)] call
2ee30 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
2ee40 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65    registered the
2ee50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73   SQL function as
2ee60 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 73  sociated with [s
2ee70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
2ee80 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  C..*/.sqlite3 *s
2ee90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2eea0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
2eeb0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
2eec0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2eed0 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20  ction Auxiliary 
2eee0 44 61 74 61 20 7b 48 31 36 32 37 30 7d 20 3c 53  Data {H16270} <S
2eef0 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
2ef00 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66   following two f
2ef10 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
2ef20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53  used by scalar S
2ef30 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
2ef40 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
2ef50 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  adata with argum
2ef60 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
2ef70 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
2ef80 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
2ef90 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
2efa0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
2efb0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
2efc0 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
2efd0 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
2efe0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
2eff0 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
2f000 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70  etadata may be p
2f010 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d  reserved. This m
2f020 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66  ay.** be used, f
2f030 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61  or example, to a
2f040 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70  dd a regular-exp
2f050 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67  ression matching
2f060 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74   scalar.** funct
2f070 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
2f080 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
2f090 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2f0a0 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73  ion is stored as
2f0b0 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73  .** metadata ass
2f0c0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2f0d0 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65   SQL value passe
2f0e0 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72  d as the regular
2f0f0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70   expression.** p
2f100 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d  attern.  The com
2f110 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78  piled regular ex
2f120 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
2f130 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70  reused on multip
2f140 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  le.** invocation
2f150 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2f160 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74  nction so that t
2f170 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74  he original patt
2f180 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f  ern string.** do
2f190 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2f1a0 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20  e recompiled on 
2f1b0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  each invocation.
2f1c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2f1d0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2f1e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2f1f0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2f200 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
2f210 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
2f220 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
2f230 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
2f240 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
2f250 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
2f260 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
2f270 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2f280 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64  ion. If no metad
2f290 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65  ata has been eve
2f2a0 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f  r.** been set fo
2f2b0 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  r the Nth argume
2f2c0 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nt of the functi
2f2d0 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f  on, or if the co
2f2e0 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66  rresponding.** f
2f2f0 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
2f300 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69  r has changed si
2f310 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74  nce the meta-dat
2f320 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68  a was set,.** th
2f330 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  en sqlite3_get_a
2f340 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73  uxdata() returns
2f350 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2f360 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2f370 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
2f380 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
2f390 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
2f3a0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69   pointed to by i
2f3b0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
2f3c0 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   as the metadata
2f3d0 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
2f3e0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
2f3f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2f400 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
2f410 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
2f420 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
2f430 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67  et_auxdata() mig
2f440 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64  ht return this d
2f450 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a  ata, if it has.*
2f460 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72  * not been destr
2f470 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69  oyed..** If it i
2f480 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
2f490 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
2f4a0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
2f4b0 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20   function given 
2f4c0 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  by the 4th param
2f4d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2f4e0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e  set_auxdata() on
2f4f0 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61  .** the metadata
2f500 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   when the corres
2f510 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
2f520 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
2f530 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  es.** or when th
2f540 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2f550 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68  completes, which
2f560 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
2f570 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
2f580 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74  s free to call t
2f590 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e  he destructor an
2f5a0 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20  d drop metadata 
2f5b0 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65  on any.** parame
2f5c0 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74  ter of any funct
2f5d0 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e  ion at any time.
2f5e0 20 20 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61    The only guara
2f5f0 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20  ntee is that.** 
2f600 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77  the destructor w
2f610 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65  ill be called be
2f620 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74  fore the metadat
2f630 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a  a is dropped..**
2f640 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c  .** In practice,
2f650 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
2f660 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
2f670 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
2f680 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  r.** expressions
2f690 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61   that are consta
2f6a0 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  nt at compile ti
2f6b0 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65  me. This include
2f6c0 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  s literal.** val
2f6d0 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69  ues and SQL vari
2f6e0 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ables..**.** The
2f6f0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
2f700 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2f710 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2f720 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2f730 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2f740 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49  running..**.** I
2f750 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2f760 20 7b 48 31 36 32 37 32 7d 20 54 68 65 20 5b 73   {H16272} The [s
2f770 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2f780 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ta(C,N)] interfa
2f790 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2f7a0 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  nter.**         
2f7b0 20 74 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73   to metadata ass
2f7c0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2f7d0 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   Nth parameter o
2f7e0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2f7f0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  on.**          w
2f800 68 6f 73 65 20 63 6f 6e 74 65 78 74 20 69 73 20  hose context is 
2f810 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  C, or NULL if th
2f820 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61  ere is no metada
2f830 74 61 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ta associated.**
2f840 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74            with t
2f850 68 61 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  hat parameter..*
2f860 2a 0a 2a 2a 20 7b 48 31 36 32 37 34 7d 20 54 68  *.** {H16274} Th
2f870 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
2f880 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d  uxdata(C,N,P,D)]
2f890 20 69 6e 74 65 72 66 61 63 65 20 61 73 73 69 67   interface assig
2f8a0 6e 73 20 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a  ns a metadata.**
2f8b0 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65            pointe
2f8c0 72 20 50 20 74 6f 20 74 68 65 20 4e 74 68 20 70  r P to the Nth p
2f8d0 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
2f8e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  SQL function wit
2f8f0 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2a 0a  h context C..**.
2f900 2a 2a 20 7b 48 31 36 32 37 36 7d 20 53 51 4c 69  ** {H16276} SQLi
2f910 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
2f920 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
2f930 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72  with a single ar
2f940 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  gument.**       
2f950 20 20 20 77 68 69 63 68 20 69 73 20 74 68 65 20     which is the 
2f960 6d 65 74 61 64 61 74 61 20 70 6f 69 6e 74 65 72  metadata pointer
2f970 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63   P following a c
2f980 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  all to.**       
2f990 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f     [sqlite3_set_
2f9a0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29  auxdata(C,N,P,D)
2f9b0 5d 20 77 68 65 6e 20 53 51 4c 69 74 65 20 63 65  ] when SQLite ce
2f9c0 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20  ases to hold.** 
2f9d0 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 74           the met
2f9e0 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  adata..**.** {H1
2f9f0 36 32 37 37 7d 20 53 51 4c 69 74 65 20 63 65 61  6277} SQLite cea
2fa00 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61  ses to hold meta
2fa10 64 61 74 61 20 66 6f 72 20 61 6e 20 53 51 4c 20  data for an SQL 
2fa20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
2fa30 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  er.**          w
2fa40 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  hen the value of
2fa50 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
2fa60 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  changes..**.** {
2fa70 48 31 36 32 37 38 7d 20 57 68 65 6e 20 5b 73 71  H16278} When [sq
2fa80 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2fa90 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69  a(C,N,P,D)] is i
2faa0 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64 65 73 74  nvoked, the dest
2fab0 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ructor.**       
2fac0 20 20 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72     is called for
2fad0 20 61 6e 79 20 70 72 69 6f 72 20 6d 65 74 61 64   any prior metad
2fae0 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
2faf0 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
2fb00 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
2fb10 20 20 63 6f 6e 74 65 78 74 20 43 20 61 6e 64 20    context C and 
2fb20 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a  parameter N..**.
2fb30 2a 2a 20 7b 48 31 36 32 37 39 7d 20 53 51 4c 69  ** {H16279} SQLi
2fb40 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73  te will call des
2fb50 74 72 75 63 74 6f 72 73 20 66 6f 72 20 61 6e 79  tructors for any
2fb60 20 6d 65 74 61 64 61 74 61 20 69 74 20 69 73 20   metadata it is 
2fb70 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20  holding.**      
2fb80 20 20 20 20 69 6e 20 61 20 70 61 72 74 69 63 75      in a particu
2fb90 6c 61 72 20 5b 70 72 65 70 61 72 65 64 20 73 74  lar [prepared st
2fba0 61 74 65 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20  atement] S when 
2fbb0 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
2fbc0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65     [sqlite3_rese
2fbd0 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  t(S)] or [sqlite
2fbe0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69  3_finalize(S)] i
2fbf0 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69  s called..*/.voi
2fc00 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
2fc10 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
2fc20 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
2fc30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
2fc40 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
2fc50 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2fc60 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
2fc70 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
2fc80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2fc90 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
2fca0 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
2fcb0 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 48 31  tor Behavior {H1
2fcc0 30 32 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a  0280} <S30100>.*
2fcd0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
2fce0 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
2fcf0 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
2fd00 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
2fd10 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
2fd20 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
2fd30 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
2fd40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2fd50 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65  b()].  If the de
2fd60 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
2fd70 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
2fd80 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
2fd90 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
2fda0 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
2fdb0 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
2fdc0 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
2fdd0 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
2fde0 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
2fdf0 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45  .  The.** SQLITE
2fe00 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
2fe10 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2fe20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
2fe30 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
2fe40 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
2fe50 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
2fe60 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
2fe70 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
2fe80 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
2fe90 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
2fea0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
2feb0 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
2fec0 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
2fed0 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
2fee0 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
2fef0 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
2ff00 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
2ff10 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
2ff20 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2ff30 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
2ff40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
2ff50 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
2ff60 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
2ff70 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
2ff80 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2ff90 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
2ffa0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
2ffb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ffc0 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
2ffd0 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
2ffe0 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d  unction {H16400}
2fff0 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
30000 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
30010 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
30020 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
30030 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
30040 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
30050 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
30060 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
30070 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
30080 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
30090 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
300a0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
300b0 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
300c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
300d0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
300e0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
300f0 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
30100 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
30110 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
30120 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
30130 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
30140 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
30150 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
30160 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
30170 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
30180 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
30190 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
301a0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
301b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
301c0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
301d0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
301e0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
301f0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
30200 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
30210 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
30220 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
30230 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
30240 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
30250 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
30260 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
30270 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
30280 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
30290 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
302a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
302b0 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
302c0 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
302d0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
302e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
302f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30300 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
30310 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
30320 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
30330 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
30340 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
30350 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
30360 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
30370 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
30380 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
30390 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
303a0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
303b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
303c0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
303d0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
303e0 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
303f0 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
30400 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
30410 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30420 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
30430 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30440 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  16() functions.*
30450 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c  * cause the impl
30460 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63  emented SQL func
30470 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e  tion to throw an
30480 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53   exception..** S
30490 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
304a0 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
304b0 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
304c0 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
304d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
304e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
304f0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
30500 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
30510 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
30520 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72  e.  SQLite inter
30530 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a  prets the error.
30540 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  ** message strin
30550 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
30560 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73  esult_error() as
30570 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a   UTF-8. SQLite.*
30580 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
30590 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
305a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
305b0 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
305c0 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
305d0 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65  e order.  If the
305e0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
305f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
30600 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
30610 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30620 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
30630 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
30640 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
30650 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
30660 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
30670 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
30680 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
30690 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61   If the third pa
306a0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
306b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
306c0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
306d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
306e0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
306f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
30700 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
30710 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
30720 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
30730 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
30740 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
30750 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ge..** The sqlit
30760 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
30770 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
30780 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
30790 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20  * routines make 
307a0 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  a private copy o
307b0 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  f the error mess
307c0 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a  age text before.
307d0 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20  ** they return. 
307e0 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c   Hence, the call
307f0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  ing function can
30800 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a   deallocate or.*
30810 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78  * modify the tex
30820 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74  t after they ret
30830 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d  urn without harm
30840 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
30850 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
30860 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68  de() function ch
30870 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20  anges the error 
30880 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  code.** returned
30890 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20   by SQLite as a 
308a0 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72  result of an err
308b0 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e  or in a function
308c0 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a  .  By default,.*
308d0 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
308e0 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
308f0 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e 74 20  .  A subsequent 
30900 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
30910 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
30920 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
30930 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
30940 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
30950 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
30960 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ROR..**.** The s
30970 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f  qlite3_result_to
30980 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  obig() interface
30990 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
309a0 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
309b0 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
309c0 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
309d0 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20  BLOB is to long 
309e0 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
309f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
30a00 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69  result_nomem() i
30a10 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
30a20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
30a30 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
30a40 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
30a50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
30a60 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  failed..**.** Th
30a70 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30a80 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
30a90 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
30aa0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
30ab0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30ac0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
30ad0 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
30ae0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
30af0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
30b00 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
30b10 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
30b20 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
30b30 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
30b40 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
30b50 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
30b60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
30b70 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
30b80 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
30b90 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
30ba0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
30bb0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
30bc0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
30bd0 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
30be0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
30bf0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
30c00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30c10 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
30c20 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
30c30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
30c40 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
30c50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
30c60 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
30c70 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
30c80 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
30c90 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
30ca0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
30cb0 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
30cc0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
30cd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30ce0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
30cf0 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
30d00 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
30d10 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
30d20 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
30d30 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
30d40 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
30d50 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
30d60 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
30d70 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74  tively..** SQLit
30d80 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
30d90 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
30da0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
30db0 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
30dc0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
30dd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
30de0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
30df0 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
30e00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
30e10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
30e20 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
30e30 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
30e40 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
30e50 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
30e60 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
30e70 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  er.** through th
30e80 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
30e90 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68  racter..** If th
30ea0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
30eb0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
30ec0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
30ed0 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
30ee0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
30ef0 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
30f00 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
30f10 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
30f20 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
30f30 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
30f40 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
30f50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30f60 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
30f70 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
30f80 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
30f90 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
30fa0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
30fb0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
30fc0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
30fd0 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
30fe0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
30ff0 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
31000 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
31010 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
31020 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
31030 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
31040 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
31050 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
31060 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20  ..** If the 4th 
31070 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
31080 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31090 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
310a0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
310b0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
310c0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
310d0 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
310e0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
310f0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
31100 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
31110 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
31120 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
31130 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
31140 74 68 65 20 69 74 20 6f 72 20 63 61 6c 6c 20 61  the it or call a
31150 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e   destructor when
31160 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
31170 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
31180 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
31190 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
311a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
311b0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
311c0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
311d0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
311e0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
311f0 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e  tant SQLITE_TRAN
31200 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51  SIENT.** then SQ
31210 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
31220 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  y of the result 
31230 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69  into space obtai
31240 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d  ned from.** from
31250 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
31260 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65  ()] before it re
31270 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  turns..**.** The
31280 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31290 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
312a0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
312b0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
312c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
312d0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
312e0 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
312f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
31300 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
31310 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
31320 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
31330 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
31340 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
31350 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
31360 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
31370 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
31380 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
31390 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
313a0 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
313b0 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
313c0 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
313d0 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
313e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
313f0 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
31400 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b  out harm..** A [
31410 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
31420 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
31430 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
31440 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
31450 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
31460 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
31470 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
31480 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
31490 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
314a0 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
314b0 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
314c0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
314d0 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
314e0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
314f0 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
31500 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
31510 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
31520 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
31530 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31540 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
31550 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
31560 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
31570 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
31580 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
31590 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  fined..**.** INV
315a0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
315b0 48 31 36 34 30 33 7d 20 54 68 65 20 64 65 66 61  H16403} The defa
315c0 75 6c 74 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ult return value
315d0 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75   from any SQL fu
315e0 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a  nction is NULL..
315f0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 36 7d 20 54  **.** {H16406} T
31600 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
31610 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
31620 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
31630 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
31640 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
31650 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
31660 6f 20 62 65 20 61 20 42 4c 4f 42 20 74 68 61 74  o be a BLOB that
31670 20 69 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20   is N bytes.**  
31680 20 20 20 20 20 20 20 20 69 6e 20 6c 65 6e 67 74          in lengt
31690 68 20 61 6e 64 20 77 69 74 68 20 63 6f 6e 74 65  h and with conte
316a0 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  nt pointed to by
316b0 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30   V..**.** {H1640
316c0 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
316d0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c  result_double(C,
316e0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
316f0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
31700 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
31710 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
31720 20 74 6f 20 62 65 20 74 68 65 20 66 6c 6f 61 74   to be the float
31730 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
31740 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 32  V..**.** {H16412
31750 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
31760 65 73 75 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c  esult_error(C,V,
31770 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  N)] interface ch
31780 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
31790 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
317a0 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
317b0 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
317c0 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
317d0 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
317e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61  [SQLITE_ERROR] a
317f0 6e 64 20 61 20 55 54 46 2d 38 20 65 72 72 6f 72  nd a UTF-8 error
31800 20 6d 65 73 73 61 67 65 20 63 6f 70 69 65 64 20   message copied 
31810 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65  from V up to the
31820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 72  .**          fir
31830 73 74 20 7a 65 72 6f 20 62 79 74 65 20 6f 72 20  st zero byte or 
31840 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72  until N bytes ar
31850 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70  e read if N is p
31860 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  ositive..**.** {
31870 48 31 36 34 31 35 7d 20 54 68 65 20 5b 73 71 6c  H16415} The [sql
31880 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31890 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65  r16(C,V,N)] inte
318a0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
318b0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
318c0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75       value of fu
318d0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
318e0 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
318f0 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
31900 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
31910 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46  ERROR] and a UTF
31920 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
31930 6f 72 64 65 72 20 65 72 72 6f 72 20 6d 65 73 73  order error mess
31940 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  age.**          
31950 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70  copied from V up
31960 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
31970 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72  ro terminator or
31980 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a   until N bytes.*
31990 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 72  *          are r
319a0 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69  ead if N is posi
319b0 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  tive..**.** {H16
319c0 34 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  418} The [sqlite
319d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
319e0 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74 65 72 66  oobig(C)] interf
319f0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
31a00 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
31a10 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
31a20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
31a30 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
31a40 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  th error code.**
31a50 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
31a60 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e  E_TOOBIG] and an
31a70 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
31a80 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
31a90 2a 20 7b 48 31 36 34 32 31 7d 20 54 68 65 20 5b  * {H16421} The [
31aa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31ab0 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69  rror_nomem(C)] i
31ac0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
31ad0 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
31ae0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
31af0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20   the function C 
31b00 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69  to be an excepti
31b10 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f  on with error co
31b20 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  de.**          [
31b30 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e  SQLITE_NOMEM] an
31b40 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  d an appropriate
31b50 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
31b60 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 34 7d 20 54  **.** {H16424} T
31b70 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
31b80 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c  lt_error_code(C,
31b90 45 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  E)] interface ch
31ba0 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
31bb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
31bc0 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ue of the functi
31bd0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
31be0 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
31bf0 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20  or code E..**   
31c00 20 20 20 20 20 20 20 54 68 65 20 65 72 72 6f 72         The error
31c10 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 69 73   message text is
31c20 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a   unchanged..**.*
31c30 2a 20 7b 48 31 36 34 32 37 7d 20 54 68 65 20 5b  * {H16427} The [
31c40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
31c50 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61  nt(C,V)] interfa
31c60 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
31c70 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
31c80 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
31c90 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
31ca0 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76  32-bit integer v
31cb0 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48  alue V..**.** {H
31cc0 31 36 34 33 30 7d 20 54 68 65 20 5b 73 71 6c 69  16430} The [sqli
31cd0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
31ce0 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
31cf0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
31d00 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
31d10 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
31d20 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 36 34  n C to be the 64
31d30 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c  -bit integer val
31d40 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ue V..**.** {H16
31d50 34 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  433} The [sqlite
31d60 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29  3_result_null(C)
31d70 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
31d80 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
31d90 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
31da0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
31db0 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
31dc0 20 7b 48 31 36 34 33 36 7d 20 54 68 65 20 5b 73   {H16436} The [s
31dd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31de0 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74  xt(C,V,N,D)] int
31df0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
31e00 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
31e10 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
31e20 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
31e30 74 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67  the UTF-8 string
31e40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56 20 75  .**          V u
31e50 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
31e60 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61  ero if N is nega
31e70 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tive.**         
31e80 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20   or the first N 
31e90 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20  bytes of V if N 
31ea0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
31eb0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 39 7d 20  .**.** {H16439} 
31ec0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
31ed0 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e  ult_text16(C,V,N
31ee0 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
31ef0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
31f00 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
31f10 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
31f20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
31f30 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
31f40 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rder.**         
31f50 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20   string V up to 
31f60 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69  the first zero i
31f70 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a  f N is negative.
31f80 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74  **          or t
31f90 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73  he first N bytes
31fa0 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f   of V if N is no
31fb0 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
31fc0 2a 20 7b 48 31 36 34 34 32 7d 20 54 68 65 20 5b  * {H16442} The [
31fd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31fe0 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29  ext16be(C,V,N,D)
31ff0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
32000 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
32010 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
32020 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
32030 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20  o be the UTF-16 
32040 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20  big-endian.**   
32050 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20         string V 
32060 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
32070 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67  zero if N is neg
32080 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
32090 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e    or the first N
320a0 20 62 79 74 65 73 20 6f 72 20 56 20 69 66 20 4e   bytes or V if N
320b0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
320c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 35 7d  ..**.** {H16445}
320d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
320e0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c  sult_text16le(C,
320f0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
32100 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
32110 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
32120 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
32130 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55  on C to be the U
32140 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  TF-16 little-end
32150 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ian.**          
32160 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74  string V up to t
32170 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66  he first zero if
32180 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a   N is negative.*
32190 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
321a0 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20  e first N bytes 
321b0 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e  of V if N is non
321c0 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a  -negative..**.**
321d0 20 7b 48 31 36 34 34 38 7d 20 54 68 65 20 5b 73   {H16448} The [s
321e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
321f0 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66  lue(C,V)] interf
32200 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
32210 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
32220 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
32230 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
32240 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
32250 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
32260 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20           object 
32270 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 31  V..**.** {H16451
32280 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
32290 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43  esult_zeroblob(C
322a0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
322b0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
322c0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
322d0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
322e0 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74  C to be an N-byt
322f0 65 20 42 4c 4f 42 20 6f 66 20 61 6c 6c 20 7a 65  e BLOB of all ze
32300 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ros..**.** {H164
32310 35 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  54} The [sqlite3
32320 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d  _result_error()]
32330 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
32340 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a  sult_error16()].
32350 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
32360 72 66 61 63 65 73 20 6d 61 6b 65 20 61 20 63 6f  rfaces make a co
32370 70 79 20 6f 66 20 74 68 65 69 72 20 65 72 72 6f  py of their erro
32380 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
32390 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20  s before.**     
323a0 20 20 20 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a       returning..
323b0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 37 7d 20 49  **.** {H16457} I
323c0 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74  f the D destruct
323d0 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  or parameter to 
323e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
323f0 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  blob(C,V,N,D)],.
32400 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
32410 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32420 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c  (C,V,N,D)], [sql
32430 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32440 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  16(C,V,N,D)],.**
32450 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
32460 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
32470 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72  be(C,V,N,D)], or
32480 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
32490 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
324a0 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
324b0 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 20  is the constant 
324c0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a  [SQLITE_STATIC].
324d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
324e0 20 6e 6f 20 64 65 73 74 72 75 63 74 6f 72 20 69   no destructor i
324f0 73 20 65 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e  s ever called on
32500 20 74 68 65 20 70 6f 69 6e 74 65 72 20 56 20 61   the pointer V a
32510 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20  nd SQLite.**    
32520 20 20 20 20 20 20 61 73 73 75 6d 65 73 20 74 68        assumes th
32530 61 74 20 56 20 69 73 20 69 6d 6d 75 74 61 62 6c  at V is immutabl
32540 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 30  e..**.** {H16460
32550 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
32560 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
32570 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
32580 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
32590 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
325a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
325b0 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
325c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
325d0 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
325e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
325f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32600 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
32610 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
32620 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32630 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
32640 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61  )] is the consta
32650 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nt.**          [
32660 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
32670 5d 20 74 68 65 6e 20 74 68 65 20 69 6e 74 65 72  ] then the inter
32680 66 61 63 65 73 20 6d 61 6b 65 73 20 61 20 63 6f  faces makes a co
32690 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  py of the.**    
326a0 20 20 20 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66        content of
326b0 20 56 20 61 6e 64 20 72 65 74 61 69 6e 73 20 74   V and retains t
326c0 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b  he copy..**.** {
326d0 48 31 36 34 36 33 7d 20 49 66 20 74 68 65 20 44  H16463} If the D
326e0 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61   destructor para
326f0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
32700 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
32710 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
32720 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
32730 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c  sult_text(C,V,N,
32740 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  D)], [sqlite3_re
32750 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
32760 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
32770 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
32780 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
32790 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  N,D)], or.**    
327a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
327b0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
327c0 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65  ,V,N,D)] is some
327d0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
327e0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
327f0 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c  e constants [SQL
32800 49 54 45 5f 53 54 41 54 49 43 5d 20 61 6e 64 20  ITE_STATIC] and 
32810 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
32820 54 5d 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  T] then.**      
32830 20 20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20      SQLite will 
32840 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
32850 75 63 74 6f 72 20 44 20 77 69 74 68 20 56 20 61  uctor D with V a
32860 73 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d  s its only argum
32870 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
32880 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
32890 73 68 65 64 20 77 69 74 68 20 74 68 65 20 56 20  shed with the V 
328a0 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73  value..*/.void s
328b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
328c0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
328d0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
328e0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
328f0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
32900 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
32910 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
32920 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
32930 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32940 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
32950 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
32960 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
32970 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32980 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
32990 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
329a0 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
329b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
329c0 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
329d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
329e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
329f0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
32a00 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
32a10 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
32a20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
32a30 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
32a40 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
32a50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32a60 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
32a70 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
32a80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32a90 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
32aa0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
32ab0 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
32ac0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
32ad0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32ae0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
32af0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
32b00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
32b10 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
32b20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
32b30 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32b40 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
32b50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
32b60 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
32b70 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
32b80 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32b90 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
32ba0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32bb0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
32bc0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
32bd0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
32be0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
32bf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32c00 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
32c10 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
32c20 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
32c30 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
32c40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32c50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
32c60 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
32c70 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
32c80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32c90 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
32ca0 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
32cb0 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
32cc0 71 75 65 6e 63 65 73 20 7b 48 31 36 36 30 30 7d  quences {H16600}
32cd0 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20300>.**.** 
32ce0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
32cf0 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
32d00 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
32d10 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a  quences to the.*
32d20 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
32d30 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
32d40 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
32d50 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
32d60 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
32d70 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
32d80 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69  uence is specifi
32d90 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74  ed as a UTF-8 st
32da0 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
32db0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32dc0 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
32dd0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32de0 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
32df0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
32e00 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
32e10 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
32e20 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a  . In all cases.*
32e30 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61  * the name is pa
32e40 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
32e50 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
32e60 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
32e70 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d  third argument m
32e80 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  ay be one of the
32e90 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49   constants [SQLI
32ea0 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51  TE_UTF8],.** [SQ
32eb0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72  LITE_UTF16LE] or
32ec0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
32ed0 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
32ee0 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70  at the user-supp
32ef0 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  lied.** routine 
32f00 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61  expects to be pa
32f10 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f  ssed pointers to
32f20 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64   strings encoded
32f30 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a   using UTF-8,.**
32f40 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65   UTF-16 little-e
32f50 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
32f60 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73   big-endian, res
32f70 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a  pectively. The.*
32f80 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  * third argument
32f90 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b   might also be [
32fa0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
32fb0 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74  GNED] to indicat
32fc0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f  e that.** the ro
32fd0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f  utine expects po
32fe0 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74  inters to 16-bit
32ff0 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74   word aligned st
33000 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d  rings.** of UTF-
33010 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
33020 20 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74   byte order of t
33030 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72  he host computer
33040 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ..**.** A pointe
33050 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75  r to the user su
33060 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d  pplied routine m
33070 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
33080 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72   the fifth.** ar
33090 67 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69  gument.  If it i
330a0 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20  s NULL, this is 
330b0 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65  the same as dele
330c0 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69  ting the collati
330d0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28  on.** sequence (
330e0 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  so that SQLite c
330f0 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e  annot call it an
33100 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20  ymore)..** Each 
33110 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61  time the applica
33120 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75  tion supplied fu
33130 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
33140 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a  d, it is passed.
33150 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20  ** as its first 
33160 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79  parameter a copy
33170 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61   of the void* pa
33180 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
33190 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  th argument.** t
331a0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
331b0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20  _collation() or 
331c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
331d0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  ollation16()..**
331e0 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
331f0 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  g arguments to t
33200 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  he application-s
33210 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20  upplied routine 
33220 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c  are two strings,
33230 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65  .** each represe
33240 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74  nted by a (lengt
33250 68 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e  h, data) pair an
33260 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65  d encoded in the
33270 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61   encoding.** tha
33280 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20  t was passed as 
33290 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
332a0 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  nt when the coll
332b0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77  ation sequence w
332c0 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  as.** registered
332d0 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 61 70 70  . {END}  The app
332e0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
332f0 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69   collation routi
33300 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ne should.** ret
33310 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65  urn negative, ze
33320 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69  ro or positive i
33330 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
33340 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
33350 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  .** equal to, or
33360 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
33370 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e  e second string.
33380 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d   i.e. (STRING1 -
33390 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a   STRING2)..**.**
333a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   The sqlite3_cre
333b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
333c0 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
333d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
333e0 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65  lation().** exce
333f0 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73  pt that it takes
33400 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65   an extra argume
33410 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65  nt which is a de
33420 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20  structor for.** 
33430 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20  the collation.  
33440 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
33450 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  s called when th
33460 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a  e collation is.*
33470 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20  * destroyed and 
33480 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79  is passed a copy
33490 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
334a0 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70  arameter void* p
334b0 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65  ointer.** of the
334c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
334d0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a  collation_v2()..
334e0 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72  ** Collations ar
334f0 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e  e destroyed when
33500 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
33510 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61  dden by later ca
33520 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f  lls to the.** co
33530 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
33540 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68   functions or wh
33550 65 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  en the [database
33560 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
33570 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20  closed.** using 
33580 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
33590 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
335a0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  NTS:.**.** {H166
335b0 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  03} A successful
335c0 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20   call to the.** 
335d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
335e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
335f0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
33600 44 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  D)] interface.**
33610 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
33620 65 72 73 20 66 75 6e 63 74 69 6f 6e 20 46 20 61  ers function F a
33630 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e  s the comparison
33640 20 66 75 6e 63 74 69 6f 6e 20 75 73 65 64 20 74   function used t
33650 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d  o.**          im
33660 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61 74 69 6f  plement collatio
33670 6e 20 58 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  n X on the [data
33680 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33690 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20   B for.**       
336a0 20 20 20 64 61 74 61 62 61 73 65 73 20 68 61 76     databases hav
336b0 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a  ing encoding E..
336c0 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 34 7d 20 53  **.** {H16604} S
336d0 51 4c 69 74 65 20 75 6e 64 65 72 73 74 61 6e 64  QLite understand
336e0 73 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  s the X paramete
336f0 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
33700 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33710 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
33720 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61  X,E,P,F,D)] as a
33730 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
33740 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46  .**          UTF
33750 2d 38 20 73 74 72 69 6e 67 20 69 6e 20 77 68 69  -8 string in whi
33760 63 68 20 63 61 73 65 20 69 73 20 69 67 6e 6f 72  ch case is ignor
33770 65 64 20 66 6f 72 20 41 53 43 49 49 20 63 68 61  ed for ASCII cha
33780 72 61 63 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20  racters and.**  
33790 20 20 20 20 20 20 20 20 69 73 20 73 69 67 6e 69          is signi
337a0 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41  ficant for non-A
337b0 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73 2e  SCII characters.
337c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 36 7d 20  .**.** {H16606} 
337d0 53 75 63 63 65 73 73 69 76 65 20 63 61 6c 6c 73  Successive calls
337e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
337f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33800 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a  (B,X,E,P,F,D)].*
33810 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
33820 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20  the same values 
33830 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c  for B, X, and E,
33840 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20   override prior 
33850 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20  values.**       
33860 20 20 20 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20     of P, F, and 
33870 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 39  D..**.** {H16609
33880 7d 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63  } If the destruc
33890 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c 69 74 65  tor D in [sqlite
338a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
338b0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
338c0 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D)].**          
338d0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
338e0 20 69 74 20 69 73 20 63 61 6c 6c 65 64 20 77 69   it is called wi
338f0 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
33900 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  en the.**       
33910 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e     collating fun
33920 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64  ction is dropped
33930 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   by SQLite..**.*
33940 2a 20 7b 48 31 36 36 31 32 7d 20 41 20 63 6f 6c  * {H16612} A col
33950 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
33960 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20  is dropped when 
33970 69 74 20 69 73 20 6f 76 65 72 6c 6f 61 64 65 64  it is overloaded
33980 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 35 7d  ..**.** {H16615}
33990 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   A collating fun
339a0 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64  ction is dropped
339b0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
339c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
339d0 20 20 20 20 20 20 20 20 20 20 69 73 20 63 6c 6f            is clo
339e0 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  sed using [sqlit
339f0 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
33a00 2a 2a 20 7b 48 31 36 36 31 38 7d 20 54 68 65 20  ** {H16618} The 
33a10 70 6f 69 6e 74 65 72 20 50 20 69 6e 20 5b 73 71  pointer P in [sq
33a20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33a30 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c  lation_v2(B,X,E,
33a40 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20  P,F,D)].**      
33a50 20 20 20 20 69 73 20 70 61 73 73 65 64 20 74 68      is passed th
33a60 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
33a70 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
33a80 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a  the comparison.*
33a90 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
33aa0 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 73 75  ion F for all su
33ab0 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
33ac0 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a  ions of F..**.**
33ad0 20 7b 48 31 36 36 32 31 7d 20 41 20 63 61 6c 6c   {H16621} A call
33ae0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
33af0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c  ate_collation(B,
33b00 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20 65 78 61  X,E,P,F)] is exa
33b10 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ctly.**         
33b20 20 74 68 65 20 73 61 6d 65 20 61 73 20 61 20 63   the same as a c
33b30 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
33b40 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33b50 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20  _v2()] with.**  
33b60 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
33b70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
33b80 61 20 4e 55 4c 4c 20 64 65 73 74 72 75 63 74 6f  a NULL destructo
33b90 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 34  r..**.** {H16624
33ba0 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73  } Following a [s
33bb0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33bc0 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
33bd0 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,P,F,D)],.**    
33be0 20 20 20 20 20 20 53 51 4c 69 74 65 20 75 73 65        SQLite use
33bf0 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e  s the comparison
33c00 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20   function F for 
33c10 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70 61 72 69  all text compari
33c20 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  son.**          
33c30 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
33c40 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
33c50 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78  ection] B on tex
33c60 74 20 76 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a  t values that.**
33c70 20 20 20 20 20 20 20 20 20 20 75 73 65 20 74 68            use th
33c80 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75  e collating sequ
33c90 65 6e 63 65 20 6e 61 6d 65 64 20 58 2e 0a 2a 2a  ence named X..**
33ca0 0a 2a 2a 20 7b 48 31 36 36 32 37 7d 20 54 68 65  .** {H16627} The
33cb0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33cc0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58  _collation16(B,X
33cd0 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74  ,E,P,F)] works t
33ce0 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
33cf0 20 20 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f      as [sqlite3_
33d00 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33d10 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63  (B,X,E,P,F)] exc
33d20 65 70 74 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ept that the.** 
33d30 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69           collati
33d40 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20 75 6e 64  on name X is und
33d50 65 72 73 74 6f 6f 64 20 61 73 20 55 54 46 2d 31  erstood as UTF-1
33d60 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  6 in native byte
33d70 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
33d80 20 20 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54     instead of UT
33d90 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  F-8..**.** {H166
33da0 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c  30} When multipl
33db0 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e  e comparison fun
33dc0 63 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c  ctions are avail
33dd0 61 62 6c 65 20 66 6f 72 20 74 68 65 20 73 61 6d  able for the sam
33de0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
33df0 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
33e00 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f 73 65 73  , SQLite chooses
33e10 20 74 68 65 20 6f 6e 65 20 77 68 6f 73 65 20 74   the one whose t
33e20 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
33e30 20 20 20 20 20 20 20 20 20 72 65 71 75 69 72 65           require
33e40 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
33e50 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  nt of conversion
33e60 20 66 72 6f 6d 20 74 68 65 20 64 65 66 61 75 6c   from the defaul
33e70 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65  t.**          te
33e80 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74  xt encoding of t
33e90 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a  he database..*/.
33ea0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
33eb0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
33ec0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
33ed0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
33ee0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
33ef0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
33f00 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
33f10 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
33f20 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
33f30 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
33f40 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33f50 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
33f60 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
33f70 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
33f80 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
33f90 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
33fa0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
33fb0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
33fc0 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
33fd0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
33fe0 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
33ff0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34000 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
34010 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f  e3*, .  const vo
34020 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74  id *zName,.  int
34030 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
34040 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
34050 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
34060 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
34070 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
34080 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34090 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65   Collation Neede
340a0 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36  d Callbacks {H16
340b0 37 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a  700} <S20300>.**
340c0 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76  .** To avoid hav
340d0 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20  ing to register 
340e0 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  all collation se
340f0 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61  quences before a
34100 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e   database.** can
34110 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67   be used, a sing
34120 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  le callback func
34130 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
34140 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a  stered with the.
34150 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
34160 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63  nection] to be c
34170 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61  alled whenever a
34180 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  n undefined coll
34190 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
341a0 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  e is required..*
341b0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63  *.** If the func
341c0 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
341d0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
341e0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
341f0 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
34200 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
34210 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
34220 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
34230 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
34240 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
34250 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31  ed in UTF-8. {H1
34260 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33  6703} If sqlite3
34270 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
34280 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a  d16() is used,.*
34290 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20  * the names are 
342a0 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
342b0 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
342c0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
342d0 2a 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68  * A call to eith
342e0 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
342f0 61 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e  aces any existin
34300 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  g callback..**.*
34310 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
34320 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
34330 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
34340 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
34350 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
34360 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
34370 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
34380 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
34390 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
343a0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
343b0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
343c0 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
343d0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
343e0 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  on.  The third a
343f0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
34400 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
34410 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
34420 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
34430 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
34440 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
34450 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
34460 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
34470 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
34480 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54  ion required.  T
34490 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
344a0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
344b0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
344c0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
344d0 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uence..**.** The
344e0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
344f0 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
34500 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63  er the desired c
34510 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  ollation using.*
34520 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
34530 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20  e_collation()], 
34540 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
34550 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20  collation16()], 
34560 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
34570 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
34580 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  v2()]..**.** INV
34590 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
345a0 48 31 36 37 30 32 7d 20 41 20 73 75 63 63 65 73  H16702} A succes
345b0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
345c0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
345d0 6e 65 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a  needed(D,P,F)].*
345e0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
345f0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
34600 5f 6e 65 65 64 65 64 31 36 28 44 2c 50 2c 46 29  _needed16(D,P,F)
34610 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20 20 20 20  ] causes.**     
34620 20 20 20 20 20 74 68 65 20 5b 64 61 74 61 62 61       the [databa
34630 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
34640 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62   to invoke callb
34650 61 63 6b 20 46 20 77 69 74 68 20 66 69 72 73 74  ack F with first
34660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
34670 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65  ameter P wheneve
34680 72 20 69 74 20 6e 65 65 64 73 20 61 20 63 6f 6d  r it needs a com
34690 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e  parison function
346a0 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20 20   for a.**       
346b0 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71     collating seq
346c0 75 65 6e 63 65 20 74 68 61 74 20 69 74 20 64 6f  uence that it do
346d0 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75  es not know abou
346e0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 34  t..**.** {H16704
346f0 7d 20 45 61 63 68 20 73 75 63 63 65 73 73 66 75  } Each successfu
34700 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
34710 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
34720 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ded()] or.**    
34730 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
34740 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
34750 36 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74  6()] overrides t
34760 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 69  he callback regi
34770 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  stered.**       
34780 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b     on the same [
34790 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
347a0 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72 20 63 61  ion] by prior ca
347b0 6c 6c 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  lls to either.**
347c0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
347d0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37  ace..**.** {H167
347e0 30 36 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  06} The name of 
347f0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 63 6f  the requested co
34800 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
34810 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 0a 2a   passed in the.*
34820 2a 20 20 20 20 20 20 20 20 20 20 34 74 68 20 70  *          4th p
34830 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
34840 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20 55  callback is in U
34850 54 46 2d 38 20 69 66 20 74 68 65 20 63 61 6c 6c  TF-8 if the call
34860 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
34870 20 77 61 73 20 72 65 67 69 73 74 65 72 65 64 20   was registered 
34880 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
34890 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
348a0 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
348b0 20 20 20 69 73 20 69 6e 20 55 54 46 2d 31 36 20     is in UTF-16 
348c0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
348d0 72 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63  r if the callbac
348e0 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20  k was.**        
348f0 20 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69    registered usi
34900 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ng [sqlite3_coll
34910 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
34920 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
34930 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
34940 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
34950 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
34960 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
34970 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
34980 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
34990 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
349a0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
349b0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
349c0 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
349d0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
349e0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
349f0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
34a00 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
34a10 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
34a20 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
34a30 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
34a40 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
34a50 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
34a60 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
34a70 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
34a80 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
34a90 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
34aa0 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
34ab0 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
34ac0 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
34ad0 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
34ae0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
34af0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
34b00 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
34b10 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
34b20 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
34b30 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
34b40 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
34b50 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
34b60 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
34b70 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
34b80 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
34b90 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
34ba0 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
34bb0 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
34bc0 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
34bd0 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
34be0 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
34bf0 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
34c00 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
34c10 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
34c20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
34c30 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
34c40 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
34c50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
34c60 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
34c70 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
34c80 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
34c90 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
34ca0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
34cb0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
34cc0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
34cd0 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
34ce0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73  ** CAPI3REF: Sus
34cf0 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46  pend Execution F
34d00 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20  or A Short Time 
34d10 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 34 31 30  {H10530} <S40410
34d20 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
34d30 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
34d40 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
34d50 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
34d60 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
34d70 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
34d80 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
34d90 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
34da0 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
34db0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
34dc0 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
34dd0 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
34de0 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
34df0 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
34e00 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
34e10 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
34e20 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
34e30 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
34e40 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
34e50 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
34e60 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
34e70 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
34e80 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
34e90 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
34ea0 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
34eb0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51  turned..**.** SQ
34ec0 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
34ed0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
34ee0 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
34ef0 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
34f00 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
34f10 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
34f20 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ject..**.** INVA
34f30 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
34f40 31 30 35 33 33 7d 20 54 68 65 20 5b 73 71 6c 69  10533} The [sqli
34f50 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e  te3_sleep(M)] in
34f60 74 65 72 66 61 63 65 20 69 6e 76 6f 6b 65 73 20  terface invokes 
34f70 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a 20 20 20  the xSleep.**   
34f80 20 20 20 20 20 20 20 6d 65 74 68 6f 64 20 6f 66         method of
34f90 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
34fa0 6c 69 74 65 33 5f 76 66 73 7c 56 46 53 5d 20 69  lite3_vfs|VFS] i
34fb0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 20 20  n order to.**   
34fc0 20 20 20 20 20 20 20 73 75 73 70 65 6e 64 20 65         suspend e
34fd0 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
34fe0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 66  current thread f
34ff0 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 20  or at least.**  
35000 20 20 20 20 20 20 20 20 4d 20 6d 69 6c 6c 69 73          M millis
35010 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  econds..**.** {H
35020 31 30 35 33 36 7d 20 54 68 65 20 5b 73 71 6c 69  10536} The [sqli
35030 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e  te3_sleep(M)] in
35040 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35050 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
35060 20 20 20 20 20 20 20 20 20 20 6d 69 6c 6c 69 73            millis
35070 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20  econds of sleep 
35080 61 63 74 75 61 6c 6c 79 20 72 65 71 75 65 73 74  actually request
35090 65 64 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74  ed of the operat
350a0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
350b0 73 79 73 74 65 6d 2c 20 77 68 69 63 68 20 6d 69  system, which mi
350c0 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68  ght be larger th
350d0 61 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  an the parameter
350e0 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   M..*/.int sqlit
350f0 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a  e3_sleep(int);..
35100 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35110 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
35120 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
35130 72 61 72 79 20 46 69 6c 65 73 20 7b 48 31 30 33  rary Files {H103
35140 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a  10} <S20000>.**.
35150 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61  ** If this globa
35160 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
35170 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
35180 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
35190 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
351a0 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
351b0 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
351c0 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20  n all temporary 
351d0 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  files.** created
351e0 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   by SQLite will 
351f0 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61  be placed in tha
35200 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66  t directory.  If
35210 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
35220 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
35230 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
35240 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72   performs a sear
35250 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70  ch for an approp
35260 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  riate.** tempora
35270 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72  ry file director
35280 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e  y..**.** It is n
35290 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69 66  ot safe to modif
352a0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
352b0 6f 6e 63 65 20 61 20 5b 64 61 74 61 62 61 73 65  once a [database
352c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
352d0 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  has been opened.
352e0 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64    It is intended
352f0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
35300 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
35310 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
35320 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
35330 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
35340 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
35350 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
35360 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20   have been call 
35370 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  and remain uncha
35380 6e 67 65 64 20 74 68 65 72 65 61 66 74 65 72 2e  nged thereafter.
35390 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
353a0 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
353b0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a  temp_directory;.
353c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
353d0 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43   Test For Auto-C
353e0 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 48 31 32 39  ommit Mode {H129
353f0 33 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20  30} <S60200>.** 
35400 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63  KEYWORDS: {autoc
35410 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a  ommit mode}.**.*
35420 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
35430 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69  t_autocommit() i
35440 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
35450 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
35460 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65  zero if the give
35470 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
35480 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e  ction is or is n
35490 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  ot in autocommit
354a0 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63   mode,.** respec
354b0 74 69 76 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d  tively.  Autocom
354c0 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
354d0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75  y default..** Au
354e0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
354f0 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
35500 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
35510 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20  ..** Autocommit 
35520 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c  mode is re-enabl
35530 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d  ed by a [COMMIT]
35540 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a   or [ROLLBACK]..
35550 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e  **.** If certain
35560 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73   kinds of errors
35570 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74   occur on a stat
35580 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d  ement within a m
35590 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a  ulti-statement.*
355a0 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65  * transaction (e
355b0 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20  rrors including 
355c0 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b  [SQLITE_FULL], [
355d0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a  SQLITE_IOERR],.*
355e0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
355f0 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
35600 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
35610 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
35620 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
35630 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
35640 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
35650 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
35660 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
35670 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65  t whether SQLite
35680 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
35690 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
356a0 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
356b0 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
356c0 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
356d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  tion..**.** INVA
356e0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
356f0 31 32 39 33 31 7d 20 54 68 65 20 5b 73 71 6c 69  12931} The [sqli
35700 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
35710 69 74 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65  it(D)] interface
35720 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
35730 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  o or.**         
35740 20 7a 65 72 6f 20 69 66 20 74 68 65 20 5b 64 61   zero if the [da
35750 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35760 6e 5d 20 44 20 69 73 20 6f 72 20 69 73 20 6e 6f  n] D is or is no
35770 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a  t in autocommit.
35780 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 64 65  **          mode
35790 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
357a0 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 32 7d 20 41  **.** {H12932} A
357b0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
357c0 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
357d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 33 7d 20  .**.** {H12933} 
357e0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
357f0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61  is disabled by a
35800 20 73 75 63 63 65 73 73 66 75 6c 20 5b 42 45 47   successful [BEG
35810 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  IN] statement..*
35820 2a 0a 2a 2a 20 7b 48 31 32 39 33 34 7d 20 41 75  *.** {H12934} Au
35830 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
35840 20 65 6e 61 62 6c 65 64 20 62 79 20 61 20 73 75   enabled by a su
35850 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54  ccessful [COMMIT
35860 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a  ] or [ROLLBACK].
35870 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74  **          stat
35880 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53  ement..**.** ASS
35890 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
358a0 7b 41 31 32 39 33 36 7d 20 49 66 20 61 6e 6f 74  {A12936} If anot
358b0 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
358c0 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
358d0 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
358e0 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20  database.**     
358f0 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20       connection 
35900 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
35910 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
35920 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
35930 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
35940 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
35950 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
35960 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
35970 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
35980 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68  API3REF: Find Th
35990 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
359a0 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20  e Of A Prepared 
359b0 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 32  Statement {H1312
359c0 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a  0} <S60600>.**.*
359d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
359e0 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
359f0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64  e returns the [d
35a00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35a10 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f  on] handle.** to
35a20 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72   which a [prepar
35a30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
35a40 6c 6f 6e 67 73 2e 20 20 54 68 65 20 64 61 74 61  longs.  The data
35a50 62 61 73 65 20 68 61 6e 64 6c 65 20 72 65 74 75  base handle retu
35a60 72 6e 65 64 20 62 79 0a 2a 2a 20 73 71 6c 69 74  rned by.** sqlit
35a70 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20  e3_db_handle is 
35a80 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
35a90 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61  e handle that wa
35aa0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
35ab0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
35ac0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
35ad0 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69  v2()] call (or i
35ae0 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61  ts variants) tha
35af0 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a  t was used to.**
35b00 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74   create the stat
35b10 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72  ement in the fir
35b20 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  st place..**.** 
35b30 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
35b40 2a 20 7b 48 31 33 31 32 33 7d 20 54 68 65 20 5b  * {H13123} The [
35b50 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
35b60 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(S)] interface 
35b70 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
35b80 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  r.**          to
35b90 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
35ba0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63  onnection] assoc
35bb0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 0a 2a  iated with the.*
35bc0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
35bd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
35be0 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  S..*/.sqlite3 *s
35bf0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
35c00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
35c10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35c20 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20  : Find the next 
35c30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35c40 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c 53 36 30  nt {H13140} <S60
35c50 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600>.**.** This 
35c60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
35c70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
35c80 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
35c90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
35ca0 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
35cb0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
35cc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35cd0 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 70  tion] pDb.  If p
35ce0 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
35cf0 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66  then this interf
35d00 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
35d10 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
35d20 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
35d30 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61  ement.** associa
35d40 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74  ted with the dat
35d50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35d60 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 70 72 65   pDb.  If no pre
35d70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
35d80 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
35d90 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
35da0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
35db0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
35dc0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
35dd0 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 33 7d 20 49  **.** {H13143} I
35de0 66 20 44 20 69 73 20 61 20 5b 64 61 74 61 62 61  f D is a [databa
35df0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
35e00 68 61 74 20 68 6f 6c 64 73 20 6f 6e 65 20 6f 72  hat holds one or
35e10 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20   more.**        
35e20 20 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 5b 70    unfinalized [p
35e30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
35e40 74 73 5d 20 61 6e 64 20 53 20 69 73 20 61 20 4e  ts] and S is a N
35e50 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 0a 2a 2a 20  ULL pointer,.** 
35e60 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73           then [s
35e70 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
35e80 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20  (D, S)] routine 
35e90 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 70  shall return a p
35ea0 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ointer.**       
35eb0 20 20 20 74 6f 20 6f 6e 65 20 6f 66 20 74 68 65     to one of the
35ec0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
35ed0 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
35ee0 77 69 74 68 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  with D..**.** {H
35ef0 31 33 31 34 36 7d 20 49 66 20 44 20 69 73 20 61  13146} If D is a
35f00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35f10 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64  ction] that hold
35f20 73 20 6e 6f 20 75 6e 66 69 6e 61 6c 69 7a 65 64  s no unfinalized
35f30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
35f40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
35f50 73 5d 20 61 6e 64 20 53 20 69 73 20 61 20 4e 55  s] and S is a NU
35f60 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
35f70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
35f80 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
35f90 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73  D, S)] routine s
35fa0 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e 55  hall return a NU
35fb0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
35fc0 2a 20 7b 48 31 33 31 34 39 7d 20 49 66 20 53 20  * {H13149} If S 
35fd0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
35fe0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65  tatement] in the
35ff0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36000 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20  ction] D.**     
36010 20 20 20 20 20 61 6e 64 20 53 20 69 73 20 6e 6f       and S is no
36020 74 20 74 68 65 20 6c 61 73 74 20 70 72 65 70 61  t the last prepa
36030 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  red statement in
36040 20 44 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20   D, then.**     
36050 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65       [sqlite3_ne
36060 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72  xt_stmt(D, S)] r
36070 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74  outine shall ret
36080 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  urn a pointer.**
36090 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
360a0 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73   next prepared s
360b0 74 61 74 65 6d 65 6e 74 20 69 6e 20 44 20 61 66  tatement in D af
360c0 74 65 72 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ter S..**.** {H1
360d0 33 31 35 32 7d 20 49 66 20 53 20 69 73 20 74 68  3152} If S is th
360e0 65 20 6c 61 73 74 20 5b 70 72 65 70 61 72 65 64  e last [prepared
360f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74   statement] in t
36100 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
36110 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36120 69 6f 6e 5d 20 44 20 74 68 65 6e 20 74 68 65 20  ion] D then the 
36130 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
36140 6d 74 28 44 2c 20 53 29 5d 0a 2a 2a 20 20 20 20  mt(D, S)].**    
36150 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20 73 68        routine sh
36160 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e 55 4c  all return a NUL
36170 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
36180 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
36190 0a 2a 2a 20 7b 41 31 33 31 35 34 7d 20 54 68 65  .** {A13154} The
361a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
361b0 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44  ction] pointer D
361c0 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a   in a call to.**
361d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
361e0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
361f0 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
36200 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
36210 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
36220 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20  nnection and in 
36230 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20  particular must 
36240 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  not be a NULL po
36250 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65  inter..*/.sqlite
36260 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f  3_stmt *sqlite3_
36270 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65  next_stmt(sqlite
36280 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f  3 *pDb, sqlite3_
36290 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
362a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
362b0 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61  ommit And Rollba
362c0 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ck Notification 
362d0 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 35  Callbacks {H1295
362e0 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a  0} <S60400>.**.*
362f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
36300 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  mmit_hook() inte
36310 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
36320 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
36330 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
36340 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
36350 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63  transaction is c
36360 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79  ommitted..** Any
36370 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
36380 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
36390 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
363a0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
363b0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
363c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
363d0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
363e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  The sqlite3_roll
363f0 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  back_hook() inte
36400 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
36410 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
36420 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
36430 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
36440 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63  transaction is c
36450 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79  ommitted..** Any
36460 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
36470 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
36480 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
36490 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
364a0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
364b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
364c0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
364d0 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
364e0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
364f0 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ugh to the callb
36500 61 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ack..** If the c
36510 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d  allback on a com
36520 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f  mit hook functio
36530 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  n returns non-ze
36540 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ro,.** then the 
36550 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72  commit is conver
36560 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
36570 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ack..**.** If an
36580 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
36590 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
365a0 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a  gistered, its.**
365b0 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72   pArg value is r
365c0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
365d0 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  ise NULL is retu
365e0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69  rned..**.** Regi
365f0 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66  stering a NULL f
36600 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73  unction disables
36610 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
36620 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72  *.** For the pur
36630 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50  poses of this AP
36640 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  I, a transaction
36650 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65   is said to have
36660 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20   been.** rolled 
36670 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69  back if an expli
36680 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73  cit "ROLLBACK" s
36690 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63  tatement is exec
366a0 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65  uted, or.** an e
366b0 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69  rror or constrai
366c0 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70  nt causes an imp
366d0 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74  licit rollback t
366e0 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20  o occur..** The 
366f0 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
36700 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
36710 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
36720 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  n is.** automati
36730 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
36740 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61  k because the da
36750 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36760 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  n is closed..** 
36770 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c  The rollback cal
36780 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76  lback is not inv
36790 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61  oked if a transa
367a0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c  ction is.** roll
367b0 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
367c0 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63  a commit callbac
367d0 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a  k returned non-z
367e0 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43  ero..** <todo> C
367f0 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74  heck on this </t
36800 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  odo>.**.** INVAR
36810 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
36820 32 39 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2951} The [sqlit
36830 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44  e3_commit_hook(D
36840 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
36850 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a   registers the.*
36860 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
36870 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74  ack function F t
36880 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  o be invoked wit
36890 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
368a0 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  never.**        
368b0 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20    a transaction 
368c0 63 6f 6d 6d 69 74 73 20 6f 6e 20 74 68 65 20 5b  commits on the [
368d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
368e0 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ion] D..**.** {H
368f0 31 32 39 35 32 7d 20 54 68 65 20 5b 73 71 6c 69  12952} The [sqli
36900 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
36910 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
36920 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20  e returns the P 
36930 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20  argument.**     
36940 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 70 72       from the pr
36950 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68  evious call with
36960 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
36970 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36980 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  D,.**          o
36990 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69  r NULL on the fi
369a0 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 61 20 70  rst call for a p
369b0 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
369c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
369d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 33 7d 20  .**.** {H12953} 
369e0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
369f0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
36a00 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20  k()] overwrites 
36a10 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
36a20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
36a30 72 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c  red by prior cal
36a40 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35  ls..**.** {H1295
36a50 34 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75  4} If the F argu
36a60 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
36a70 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46  _commit_hook(D,F
36a80 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  ,P)] is NULL.** 
36a90 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68           then th
36aa0 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61  e commit hook ca
36ab0 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c  llback is cancel
36ac0 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61  ed and no callba
36ad0 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ck.**          i
36ae0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
36af0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d   transaction com
36b00 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  mits..**.** {H12
36b10 39 35 35 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d  955} If the comm
36b20 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  it callback retu
36b30 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65  rns non-zero the
36b40 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a  n the commit is.
36b50 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 76  **          conv
36b60 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
36b70 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  lback..**.** {H1
36b80 32 39 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2961} The [sqlit
36b90 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
36ba0 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
36bb0 63 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65  ce registers the
36bc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
36bd0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46  lback function F
36be0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
36bf0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77  ith argument P w
36c00 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20  henever.**      
36c10 20 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f      a transactio
36c20 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20  n rolls back on 
36c30 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
36c40 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
36c50 2a 2a 20 7b 48 31 32 39 36 32 7d 20 54 68 65 20  ** {H12962} The 
36c60 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
36c70 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  k_hook(D,F,P)] i
36c80 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
36c90 20 74 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20   the P.**       
36ca0 20 20 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d     argument from
36cb0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
36cc0 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ll with the same
36cd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
36ce0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36cf0 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e  n] D, or NULL on
36d00 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a   the first call.
36d10 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
36d20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
36d30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36d40 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36   D..**.** {H1296
36d50 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  3} Each call to 
36d60 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
36d70 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72  k_hook()] overwr
36d80 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  ites the callbac
36d90 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  k.**          re
36da0 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69 6f  gistered by prio
36db0 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b  r calls..**.** {
36dc0 48 31 32 39 36 34 7d 20 49 66 20 74 68 65 20 46  H12964} If the F
36dd0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
36de0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
36df0 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e  ook(D,F,P)] is N
36e00 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
36e10 74 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63  then the rollbac
36e20 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  k hook callback 
36e30 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20  is canceled and 
36e40 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  no callback.**  
36e50 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b          is invok
36e60 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61  ed when a transa
36e70 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b  ction rolls back
36e80 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
36e90 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73  e3_commit_hook(s
36ea0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
36eb0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
36ec0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f  void *sqlite3_ro
36ed0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69  llback_hook(sqli
36ee0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f  te3*, void(*)(vo
36ef0 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  id *), void*);..
36f00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36f10 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69  Data Change Noti
36f20 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
36f30 6b 73 20 7b 48 31 32 39 37 30 7d 20 3c 53 36 30  ks {H12970} <S60
36f40 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  400>.**.** The s
36f50 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
36f60 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
36f70 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
36f80 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
36f90 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
36fa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
36fb0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
36fc0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
36fd0 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
36fe0 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
36ff0 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
37000 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
37010 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b  .** Any callback
37020 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
37030 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
37040 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  function.** for 
37050 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
37060 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
37070 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a  overridden..**.*
37080 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
37090 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
370a0 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
370b0 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
370c0 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70  n a.** row is up
370d0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
370e0 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54  or deleted..** T
370f0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
37100 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  t to the callbac
37110 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
37120 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
37130 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
37140 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a  update_hook()..*
37150 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c  * The second cal
37160 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69  lback argument i
37170 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
37180 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54  _INSERT], [SQLIT
37190 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72  E_DELETE],.** or
371a0 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d   [SQLITE_UPDATE]
371b0 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
371c0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  he operation tha
371d0 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c  t caused the cal
371e0 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69  lback.** to be i
371f0 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74  nvoked..** The t
37200 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
37210 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
37220 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
37230 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  n pointers to th
37240 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e  e.** database an
37250 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e  d table name con
37260 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65  taining the affe
37270 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65  cted row..** The
37280 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
37290 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
372a0 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f   rowid of the ro
372b0 77 2e 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f  w. In the case o
372c0 66 0a 2a 2a 20 61 6e 20 75 70 64 61 74 65 2c 20  f.** an update, 
372d0 74 68 69 73 20 69 73 20 74 68 65 20 72 6f 77 69  this is the rowi
372e0 64 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61  d after the upda
372f0 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a  te takes place..
37300 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65  **.** The update
37310 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76   hook is not inv
37320 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
37330 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73  al system tables
37340 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   are.** modified
37350 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61   (i.e. sqlite_ma
37360 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
37370 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a  sequence)..**.**
37380 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63   If another func
37390 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75  tion was previou
373a0 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20  sly registered, 
373b0 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a  its pArg value.*
373c0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  * is returned.  
373d0 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69  Otherwise NULL i
373e0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
373f0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
37400 0a 2a 2a 20 7b 48 31 32 39 37 31 7d 20 54 68 65  .** {H12971} The
37410 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
37420 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e  _hook(D,F,P)] in
37430 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
37440 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  he callback.**  
37450 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
37460 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   F to be invoked
37470 20 77 69 74 68 20 66 69 72 73 74 20 70 61 72 61   with first para
37480 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 72  meter P whenever
37490 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74  .**          a t
374a0 61 62 6c 65 20 72 6f 77 20 69 73 20 6d 6f 64 69  able row is modi
374b0 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 2c 20  fied, inserted, 
374c0 6f 72 20 64 65 6c 65 74 65 64 20 6f 6e 0a 2a 2a  or deleted on.**
374d0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64            the [d
374e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
374f0 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  on] D..**.** {H1
37500 32 39 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  2973} The [sqlit
37510 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
37520 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
37530 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
37540 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ue.**          o
37550 66 20 50 20 66 6f 72 20 74 68 65 20 70 72 65 76  f P for the prev
37560 69 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68 65  ious call on the
37570 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
37580 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a  connection] D,.*
37590 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55  *          or NU
375a0 4c 4c 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  LL for the first
375b0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   call..**.** {H1
375c0 32 39 37 35 7d 20 49 66 20 74 68 65 20 75 70 64  2975} If the upd
375d0 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  ate hook callbac
375e0 6b 20 46 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  k F in [sqlite3_
375f0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c  update_hook(D,F,
37600 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  P)].**          
37610 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
37620 20 6e 6f 20 75 70 64 61 74 65 20 63 61 6c 6c 62   no update callb
37630 61 63 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a 2a  acks are made..*
37640 2a 0a 2a 2a 20 7b 48 31 32 39 37 37 7d 20 45 61  *.** {H12977} Ea
37650 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
37660 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
37670 44 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69 64 65  D,F,P)] override
37680 73 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a  s prior calls.**
37690 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
376a0 20 73 61 6d 65 20 69 6e 74 65 72 66 61 63 65 20   same interface 
376b0 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
376c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
376d0 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ] D..**.** {H129
376e0 37 39 7d 20 54 68 65 20 75 70 64 61 74 65 20 68  79} The update h
376f0 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ook callback is 
37700 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
37710 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
37720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 61 62  .**          tab
37730 6c 65 73 20 73 75 63 68 20 61 73 20 73 71 6c 69  les such as sqli
37740 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71  te_master and sq
37750 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 20 61 72  lite_sequence ar
37760 65 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  e modified..**.*
37770 2a 20 7b 48 31 32 39 38 31 7d 20 54 68 65 20 73  * {H12981} The s
37780 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
37790 74 6f 20 74 68 65 20 75 70 64 61 74 65 20 63 61  to the update ca
377a0 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
377b0 20 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51     is one of [SQ
377c0 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
377d0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72  QLITE_DELETE] or
377e0 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d   [SQLITE_UPDATE]
377f0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  ,.**          de
37800 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
37810 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61  peration that ca
37820 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  used the callbac
37830 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e  k to be invoked.
37840 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38 33 7d 20  .**.** {H12983} 
37850 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
37860 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
37870 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
37880 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 0a  ontain pointers.
37890 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 7a  **          to z
378a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
378b0 54 46 2d 38 20 73 74 72 69 6e 67 73 20 77 68 69  TF-8 strings whi
378c0 63 68 20 61 72 65 20 74 68 65 20 6e 61 6d 65 73  ch are the names
378d0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
378e0 20 20 20 20 64 61 74 61 62 61 73 65 20 61 6e 64      database and
378f0 20 74 61 62 6c 65 20 74 68 61 74 20 69 73 20 62   table that is b
37900 65 69 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a 2a  eing updated...*
37910 2a 20 7b 48 31 32 39 38 35 7d 20 54 68 65 20 66  * {H12985} The f
37920 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61  inal callback pa
37930 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 72  rameter is the r
37940 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 20  owid of the row 
37950 61 66 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  after.**        
37960 20 20 74 68 65 20 63 68 61 6e 67 65 20 6f 63 63    the change occ
37970 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  urs..*/.void *sq
37980 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
37990 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  k(.  sqlite3*, .
379a0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a    void(*)(void *
379b0 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74  ,int ,char const
379c0 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c   *,char const *,
379d0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a  sqlite3_int64),.
379e0 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a    void*.);../*.*
379f0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
37a00 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68  le Or Disable Sh
37a10 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65  ared Pager Cache
37a20 20 7b 48 31 30 33 33 30 7d 20 3c 53 33 30 39 30   {H10330} <S3090
37a30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
37a40 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d 20 7b  {shared cache} {
37a50 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
37a60 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  e}.**.** This ro
37a70 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
37a80 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68   disables the sh
37a90 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  aring of the dat
37aa0 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61  abase cache.** a
37ab0 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73  nd schema data s
37ac0 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65  tructures betwee
37ad0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
37ae0 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74  ection | connect
37af0 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ions].** to the 
37b00 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53  same database. S
37b10 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65  haring is enable
37b20 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
37b30 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64  t is true.** and
37b40 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65   disabled if the
37b50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c   argument is fal
37b60 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20  se..**.** Cache 
37b70 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  sharing is enabl
37b80 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ed and disabled 
37b90 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72  for an entire pr
37ba0 6f 63 65 73 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 20  ocess. {END}.** 
37bb0 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65  This is a change
37bc0 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65   as of SQLite ve
37bd0 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20  rsion 3.5.0. In 
37be0 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f  prior versions o
37bf0 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61  f SQLite,.** sha
37c00 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64  ring was enabled
37c10 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72   or disabled for
37c20 20 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70   each thread sep
37c30 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54  arately..**.** T
37c40 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67  he cache sharing
37c50 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69   mode set by thi
37c60 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65  s interface effe
37c70 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65  cts all subseque
37c80 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b  nt.** calls to [
37c90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
37ca0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
37cb0 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  2()], and [sqlit
37cc0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
37cd0 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61   Existing databa
37ce0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63  se connections c
37cf0 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20  ontinue use the 
37d00 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20  sharing mode.** 
37d10 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 66 65  that was in effe
37d20 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74  ct at the time t
37d30 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e  hey were opened.
37d40 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74  .**.** Virtual t
37d50 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20  ables cannot be 
37d60 75 73 65 64 20 77 69 74 68 20 61 20 73 68 61 72  used with a shar
37d70 65 64 20 63 61 63 68 65 2e 20 20 57 68 65 6e 20  ed cache.  When 
37d80 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
37d90 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20  is enabled, the 
37da0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
37db0 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49 20 75 73  module()] API us
37dc0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a  ed to register.*
37dd0 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * virtual tables
37de0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
37df0 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  urn an error..**
37e00 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
37e10 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
37e20 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
37e30 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
37e40 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
37e50 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
37e60 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
37e70 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
37e80 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72  wise..**.** Shar
37e90 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61  ed cache is disa
37ea0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
37eb0 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20   But this might 
37ec0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74  change in.** fut
37ed0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
37ee0 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61  SQLite.  Applica
37ef0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20  tions that care 
37f00 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20  about shared.** 
37f10 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68  cache setting sh
37f20 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c  ould set it expl
37f30 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e  icitly..**.** IN
37f40 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
37f50 7b 48 31 30 33 33 31 7d 20 41 20 73 75 63 63 65  {H10331} A succe
37f60 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
37f70 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61   of [sqlite3_ena
37f80 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
37f90 28 42 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (B)].**         
37fa0 20 77 69 6c 6c 20 65 6e 61 62 6c 65 20 6f 72 20   will enable or 
37fb0 64 69 73 61 62 6c 65 20 73 68 61 72 65 64 20 63  disable shared c
37fc0 61 63 68 65 20 6d 6f 64 65 20 66 6f 72 20 61 6e  ache mode for an
37fd0 79 20 73 75 62 73 65 71 75 65 6e 74 6c 79 0a 2a  y subsequently.*
37fe0 2a 20 20 20 20 20 20 20 20 20 20 63 72 65 61 74  *          creat
37ff0 65 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ed [database con
38000 6e 65 63 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20  nection] in the 
38010 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a  same process..**
38020 0a 2a 2a 20 7b 48 31 30 33 33 36 7d 20 57 68 65  .** {H10336} Whe
38030 6e 20 73 68 61 72 65 64 20 63 61 63 68 65 20 69  n shared cache i
38040 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b  s enabled, the [
38050 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
38060 6f 64 75 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20  odule()].**     
38070 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 77       interface w
38080 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
38090 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a  n an error..**.*
380a0 2a 20 7b 48 31 30 33 33 37 7d 20 54 68 65 20 5b  * {H10337} The [
380b0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
380c0 68 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 20  hared_cache(B)] 
380d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
380e0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  s.**          [S
380f0 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61  QLITE_OK] if sha
38100 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e  red cache was en
38110 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
38120 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a  d successfully..
38130 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 39 7d 20 53  **.** {H10339} S
38140 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
38150 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
38160 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  lt..*/.int sqlit
38170 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
38180 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a  _cache(int);../*
38190 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74  .** CAPI3REF: At
381a0 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65  tempt To Free He
381b0 61 70 20 4d 65 6d 6f 72 79 20 7b 48 31 37 33 34  ap Memory {H1734
381c0 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a  0} <S30220>.**.*
381d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
381e0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
381f0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
38200 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
38210 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
38220 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
38230 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
38240 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
38250 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
38260 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
38270 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d  rary. {END}  Mem
38280 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 68  ory used to cach
38290 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61  e database.** pa
382a0 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70  ges to improve p
382b0 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e  erformance is an
382c0 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d   example of non-
382d0 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
382e0 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c  ..** sqlite3_rel
382f0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65  ease_memory() re
38300 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
38310 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c   of bytes actual
38320 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69  ly freed,.** whi
38330 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65  ch might be more
38340 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68   or less than th
38350 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74  e amount request
38360 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
38370 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  ANTS:.**.** {H17
38380 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  341} The [sqlite
38390 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
383a0 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  (N)] interface a
383b0 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 20 20  ttempts to.**   
383c0 20 20 20 20 20 20 20 66 72 65 65 20 4e 20 62 79         free N by
383d0 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  tes of heap memo
383e0 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69  ry by deallocati
383f0 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  ng non-essential
38400 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d  .**          mem
38410 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
38420 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61  held by the data
38430 62 61 73 65 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  base library..**
38440 0a 2a 2a 20 7b 48 31 36 33 34 32 7d 20 54 68 65  .** {H16342} The
38450 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
38460 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 72 65 74  e_memory(N)] ret
38470 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 0a  urns the number.
38480 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 62  **          of b
38490 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
384a0 65 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74  eed, which might
384b0 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73   be more or less
384c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
384d0 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71  n the amount req
384e0 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  uested..*/.int s
384f0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
38500 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  emory(int);../*.
38510 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70  ** CAPI3REF: Imp
38520 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48  ose A Limit On H
38530 65 61 70 20 53 69 7a 65 20 7b 48 31 37 33 35 30  eap Size {H17350
38540 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a  } <S30220>.**.**
38550 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66   The sqlite3_sof
38560 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69  t_heap_limit() i
38570 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65 73 20  nterface places 
38580 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a  a "soft" limit.*
38590 2a 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  * on the amount 
385a0 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
385b0 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63  hat may be alloc
385c0 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  ated by SQLite..
385d0 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61  ** If an interna
385e0 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  l allocation is 
385f0 72 65 71 75 65 73 74 65 64 20 74 68 61 74 20 77  requested that w
38600 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a  ould exceed the.
38610 2a 2a 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  ** soft heap lim
38620 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  it, [sqlite3_rel
38630 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69  ease_memory()] i
38640 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72  s invoked one or
38650 0a 2a 2a 20 6d 6f 72 65 20 74 69 6d 65 73 20 74  .** more times t
38660 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73  o free up some s
38670 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 20  pace before the 
38680 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 70 65  allocation is pe
38690 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  rformed..**.** T
386a0 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c  he limit is call
386b0 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75  ed "soft", becau
386c0 73 65 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72  se if [sqlite3_r
386d0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
386e0 0a 2a 2a 20 63 61 6e 6e 6f 74 20 66 72 65 65 20  .** cannot free 
386f0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
38700 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65  y to prevent the
38710 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e   limit from bein
38720 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74  g exceeded,.** t
38730 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c  he memory is all
38740 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e  ocated anyway an
38750 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70  d the current op
38760 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
38770 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69  ..**.** A negati
38780 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65  ve or zero value
38790 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61   for N means tha
387a0 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f  t there is no so
387b0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e  ft heap limit an
387c0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  d.** [sqlite3_re
387d0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
387e0 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c  will only be cal
387f0 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20  led when memory 
38800 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a  is exhausted..**
38810 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
38820 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20  ue for the soft 
38830 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65  heap limit is ze
38840 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ro..**.** SQLite
38850 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66   makes a best ef
38860 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68  fort to honor th
38870 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
38880 74 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65  t..** But if the
38890 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
388a0 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72   cannot be honor
388b0 65 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69  ed, execution wi
388c0 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77  ll.** continue w
388d0 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20  ithout error or 
388e0 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54  notification.  T
388f0 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6