/ Hex Artifact Content
Login

Artifact b5d50f12fb9c7460a4ddfef8c1e799afaabefebf:


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 34 31 36 20 32 30 30 38 2f 31  n,v 1.416 2008/1
05f0: 31 2f 32 31 20 30 30 3a 31 30 3a 33 35 20 61 73  1/21 00:10:35 as
0600: 77 69 66 74 20 45 78 70 20 24 0a 2a 2f 0a 23 69  wift Exp $.*/.#i
0610: 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48  fndef _SQLITE3_H
0620: 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54  _.#define _SQLIT
0630: 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c  E3_H_.#include <
0640: 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a  stdarg.h>     /*
0650: 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 20   Needed for the 
0660: 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61  definition of va
0670: 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  _list */../*.** 
0680: 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e  Make sure we can
0690: 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66   call this stuff
06a0: 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69   from C++..*/.#i
06b0: 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73  fdef __cplusplus
06c0: 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65  .extern "C" {.#e
06d0: 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64  ndif.../*.** Add
06e0: 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   the ability to 
06f0: 6f 76 65 72 72 69 64 65 20 27 65 78 74 65 72 6e  override 'extern
0700: 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  '.*/.#ifndef SQL
0710: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0720: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0730: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0740: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0750: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0760: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0770: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
0780: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
0790: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
07a0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
07b0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
07c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
07d0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
07e0: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 72 66  deprecated intrf
07f0: 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 20  aces - they are 
0800: 73 75 70 70 6f 72 74 20 66 6f 72 20 62 61 63 6b  support for back
0810: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69  wards.** compati
0820: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70  bility only.  Ap
0830: 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72  plication writer
0840: 73 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72  s should be awar
0850: 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69  e that.** experi
0860: 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65  mental interface
0870: 73 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f  s are subject to
0880: 20 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74   change in point
0890: 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
08a0: 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73   These macros us
08b0: 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f  ed to resolve to
08c0: 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f   various kinds o
08d0: 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63  f compiler magic
08e0: 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67   that.** would g
08f0: 65 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20  enerate warning 
0900: 6d 65 73 73 61 67 65 73 20 77 68 65 6e 20 74 68  messages when th
0910: 65 79 20 77 65 72 65 20 75 73 65 64 2e 20 20 42  ey were used.  B
0920: 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69  ut that.** compi
0930: 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20  ler magic ended 
0940: 75 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75  up generating su
0950: 63 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62  ch a flurry of b
0960: 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68  ug reports.** th
0970: 61 74 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e  at we have taken
0980: 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20   it all out and 
0990: 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69  gone back to usi
09a0: 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f  ng simple.** noo
09b0: 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65  p macros..*/.#de
09c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52  fine SQLITE_DEPR
09d0: 45 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53  ECATED.#define S
09e0: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
09f0: 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65  AL../*.** Ensure
0a00: 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77   these symbols w
0a10: 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20  ere not defined 
0a20: 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73  by some previous
0a30: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f   header file..*/
0a40: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56  .#ifdef SQLITE_V
0a50: 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53  ERSION.# undef S
0a60: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65  QLITE_VERSION.#e
0a70: 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49  ndif.#ifdef SQLI
0a80: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0a90: 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  R.# undef SQLITE
0aa0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a  _VERSION_NUMBER.
0ab0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
0ac0: 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
0ad0: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72  Time Library Ver
0ae0: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31  sion Numbers {H1
0af0: 30 30 31 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a  0010} <S60100>.*
0b00: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
0b10: 56 45 52 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49  VERSION and SQLI
0b20: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0b30: 52 20 23 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a  R #defines in.**
0b40: 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 66   the sqlite3.h f
0b50: 69 6c 65 20 73 70 65 63 69 66 79 20 74 68 65 20  ile specify the 
0b60: 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
0b70: 65 20 77 69 74 68 20 77 68 69 63 68 0a 2a 2a 20  e with which.** 
0b80: 74 68 61 74 20 68 65 61 64 65 72 20 66 69 6c 65  that header file
0b90: 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a   is associated..
0ba0: 2a 2a 0a 2a 2a 20 54 68 65 20 22 76 65 72 73 69  **.** The "versi
0bb0: 6f 6e 22 20 6f 66 20 53 51 4c 69 74 65 20 69 73  on" of SQLite is
0bc0: 20 61 20 73 74 72 69 6e 67 20 6f 66 20 74 68 65   a string of the
0bd0: 20 66 6f 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a   form "X.Y.Z"..*
0be0: 2a 20 54 68 65 20 70 68 72 61 73 65 20 22 61 6c  * The phrase "al
0bf0: 70 68 61 22 20 6f 72 20 22 62 65 74 61 22 20 6d  pha" or "beta" m
0c00: 69 67 68 74 20 62 65 20 61 70 70 65 6e 64 65 64  ight be appended
0c10: 20 61 66 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a   after the Z..**
0c20: 20 54 68 65 20 58 20 76 61 6c 75 65 20 69 73 20   The X value is 
0c30: 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75  major version nu
0c40: 6d 62 65 72 20 61 6c 77 61 79 73 20 33 20 69 6e  mber always 3 in
0c50: 20 53 51 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65   SQLite3..** The
0c60: 20 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68   X value only ch
0c70: 61 6e 67 65 73 20 77 68 65 6e 20 62 61 63 6b 77  anges when backw
0c80: 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
0c90: 74 79 20 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20  ty is.** broken 
0ca0: 61 6e 64 20 77 65 20 69 6e 74 65 6e 64 20 74 6f  and we intend to
0cb0: 20 6e 65 76 65 72 20 62 72 65 61 6b 20 62 61 63   never break bac
0cc0: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
0cd0: 6c 69 74 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76  lity..** The Y v
0ce0: 61 6c 75 65 20 69 73 20 74 68 65 20 6d 69 6e 6f  alue is the mino
0cf0: 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  r version number
0d00: 20 61 6e 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65   and only change
0d10: 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20  s when.** there 
0d20: 61 72 65 20 6d 61 6a 6f 72 20 66 65 61 74 75 72  are major featur
0d30: 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74  e enhancements t
0d40: 68 61 74 20 61 72 65 20 66 6f 72 77 61 72 64 73  hat are forwards
0d50: 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62   compatible.** b
0d60: 75 74 20 6e 6f 74 20 62 61 63 6b 77 61 72 64 73  ut not backwards
0d70: 20 63 6f 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20   compatible..** 
0d80: 54 68 65 20 5a 20 76 61 6c 75 65 20 69 73 20 74  The Z value is t
0d90: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0da0: 72 20 61 6e 64 20 69 73 20 69 6e 63 72 65 6d 65  r and is increme
0db0: 6e 74 65 64 20 77 69 74 68 0a 2a 2a 20 65 61 63  nted with.** eac
0dc0: 68 20 72 65 6c 65 61 73 65 20 62 75 74 20 72 65  h release but re
0dd0: 73 65 74 73 20 62 61 63 6b 20 74 6f 20 30 20 77  sets back to 0 w
0de0: 68 65 6e 65 76 65 72 20 59 20 69 73 20 69 6e 63  henever Y is inc
0df0: 72 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  remented..**.** 
0e00: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
0e10: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d  e3_libversion()]
0e20: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69   and [sqlite3_li
0e30: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
0e40: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
0e50: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ANTS:.**.** {H10
0e60: 30 31 31 7d 20 54 68 65 20 53 51 4c 49 54 45 5f  011} The SQLITE_
0e70: 56 45 52 53 49 4f 4e 20 23 64 65 66 69 6e 65 20  VERSION #define 
0e80: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68  in the sqlite3.h
0e90: 20 68 65 61 64 65 72 20 66 69 6c 65 20 73 68 61   header file sha
0ea0: 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  ll.**          e
0eb0: 76 61 6c 75 61 74 65 20 74 6f 20 61 20 73 74 72  valuate to a str
0ec0: 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74  ing literal that
0ed0: 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76   is the SQLite v
0ee0: 65 72 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ersion.**       
0ef0: 20 20 20 77 69 74 68 20 77 68 69 63 68 20 74 68     with which th
0f00: 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73  e header file is
0f10: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a   associated..**.
0f20: 2a 2a 20 7b 48 31 30 30 31 34 7d 20 54 68 65 20  ** {H10014} The 
0f30: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0f40: 55 4d 42 45 52 20 23 64 65 66 69 6e 65 20 73 68  UMBER #define sh
0f50: 61 6c 6c 20 72 65 73 6f 6c 76 65 20 74 6f 20 61  all resolve to a
0f60: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20  n integer.**    
0f70: 20 20 20 20 20 20 77 69 74 68 20 74 68 65 20 76        with the v
0f80: 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20  alue (X*1000000 
0f90: 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68  + Y*1000 + Z) wh
0fa0: 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 0a  ere X, Y, and Z.
0fb0: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20  **          are 
0fc0: 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f  the major versio
0fd0: 6e 2c 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e  n, minor version
0fe0: 2c 20 61 6e 64 20 72 65 6c 65 61 73 65 20 6e 75  , and release nu
0ff0: 6d 62 65 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  mber..*/.#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20   SQLITE_VERSION 
1010: 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53 2d          "--VERS-
1020: 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  -".#define SQLIT
1030: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1040: 20 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42    --VERSION-NUMB
1050: 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ER--../*.** CAPI
1060: 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
1070: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
1080: 75 6d 62 65 72 73 20 7b 48 31 30 30 32 30 7d 20  umbers {H10020} 
1090: 3c 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S60100>.** KEYW
10a0: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10b0: 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  rsion.**.** Thes
10c0: 65 20 66 65 61 74 75 72 65 73 20 70 72 6f 76 69  e features provi
10d0: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  de the same info
10e0: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b  rmation as the [
10f0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a  SQLITE_VERSION].
1100: 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56  ** and [SQLITE_V
1110: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23  ERSION_NUMBER] #
1120: 64 65 66 69 6e 65 73 20 69 6e 20 74 68 65 20 68  defines in the h
1130: 65 61 64 65 72 2c 20 62 75 74 20 61 72 65 20 61  eader, but are a
1140: 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
1150: 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e  h the library in
1160: 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61  stead of the hea
1170: 64 65 72 20 66 69 6c 65 2e 20 20 43 61 75 74 69  der file.  Cauti
1180: 6f 75 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20  ous programmers 
1190: 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65  might.** include
11a0: 20 61 20 63 68 65 63 6b 20 69 6e 20 74 68 65 69   a check in thei
11b0: 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  r application to
11c0: 20 76 65 72 69 66 79 20 74 68 61 74 0a 2a 2a 20   verify that.** 
11d0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
11e0: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77 61  on_number() alwa
11f0: 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  ys returns the v
1200: 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  alue.** [SQLITE_
1210: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e  VERSION_NUMBER].
1220: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1230: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20  e3_libversion() 
1240: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1250: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
1260: 61 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69  ation as is.** i
1270: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65  n the sqlite3_ve
1280: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
1290: 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 66 75  onstant.  The fu
12a0: 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64  nction is provid
12b0: 65 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e  ed.** for use in
12c0: 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20   DLLs since DLL 
12d0: 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f  users usually do
12e0: 20 6e 6f 74 20 68 61 76 65 20 64 69 72 65 63 74   not have direct
12f0: 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e   access to strin
1300: 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77  g.** constants w
1310: 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a  ithin the DLL..*
1320: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1330: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 31 7d 20  .**.** {H10021} 
1340: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  The [sqlite3_lib
1350: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
1360: 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ] interface shal
1370: 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  l return.**     
1380: 20 20 20 20 20 61 6e 20 69 6e 74 65 67 65 72 20       an integer 
1390: 65 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45  equal to [SQLITE
13a0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
13b0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d  ..**.** {H10022}
13c0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65   The [sqlite3_ve
13d0: 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f  rsion] string co
13e0: 6e 73 74 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e  nstant shall con
13f0: 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tain.**         
1400: 20 74 68 65 20 74 65 78 74 20 6f 66 20 74 68 65   the text of the
1410: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
1420: 5d 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ] string..**.** 
1430: 7b 48 31 30 30 32 33 7d 20 54 68 65 20 5b 73 71  {H10023} The [sq
1440: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1450: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61  ()] function sha
1460: 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  ll return.**    
1470: 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20        a pointer 
1480: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
1490: 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20  version] string 
14a0: 63 6f 6e 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c  constant..*/.SQL
14b0: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
14c0: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
14d0: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
14e0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
14f0: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69  version(void);.i
1500: 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  nt sqlite3_libve
1510: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69  rsion_number(voi
1520: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
1530: 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65  REF: Test To See
1540: 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20   If The Library 
1550: 49 73 20 54 68 72 65 61 64 73 61 66 65 20 7b 48  Is Threadsafe {H
1560: 31 30 31 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a  10100} <S60100>.
1570: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
1580: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
1590: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
15a0: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
15b0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
15c0: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
15d0: 65 73 73 6f 72 20 6d 61 63 72 6f 20 31 20 6f 72  essor macro 1 or
15e0: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
15f0: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1600: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1610: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1620: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1630: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1640: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1650: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1660: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1670: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1680: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1690: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
16a0: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
16b0: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
16c0: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
16d0: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
16e0: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
16f0: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1700: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1710: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1720: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1730: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1740: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1750: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1760: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1770: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1780: 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  d..** The defaul
1790: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
17a0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
17b0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
17c0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
17d0: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 20 70  n be used by a p
17e0: 72 6f 67 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73  rogram to make s
17f0: 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
1800: 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
1810: 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e  e that it is lin
1820: 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73  king against was
1830: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
1840: 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65  * the desired se
1850: 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51  tting of the [SQ
1860: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1870: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68   macro..**.** Th
1880: 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c  is interface onl
1890: 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65  y reports on the
18a0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75   compile-time mu
18b0: 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f  tex setting.** o
18c0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
18d0: 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20  READSAFE] flag. 
18e0: 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
18f0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53  mpiled with.** S
1900: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1910: 3d 31 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =1 then mutexes 
1920: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
1930: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
1940: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
1950: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
1960: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
1970: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
1980: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
1990: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
19a0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
19b0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
19c0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
19d0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
19e0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54  ONFIG_MUTEX].  T
19f0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1a00: 6f 66 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  of this function
1a10: 20 73 68 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74   shows.** only t
1a20: 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6d 70 69  he default compi
1a30: 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 2c  le-time setting,
1a40: 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d   not any run-tim
1a50: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
1a60: 74 68 61 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  that setting..**
1a70: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72  .** See the [thr
1a80: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63  eading mode] doc
1a90: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
1aa0: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
1ab0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ation..**.** INV
1ac0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1ad0: 48 31 30 31 30 31 7d 20 54 68 65 20 5b 73 71 6c  H10101} The [sql
1ae0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
1af0: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c  )] function shal
1b00: 6c 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 69 66  l return zero if
1b10: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
1b20: 20 6f 6e 6c 79 20 69 66 20 53 51 4c 69 74 65 20   only if SQLite 
1b30: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1b40: 68 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20  h mutexing code 
1b50: 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  omitted..**.** {
1b60: 48 31 30 31 30 32 7d 20 54 68 65 20 76 61 6c 75  H10102} The valu
1b70: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
1b80: 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  e [sqlite3_threa
1b90: 64 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f  dsafe()] functio
1ba0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  n.**          sh
1bb0: 61 6c 6c 20 72 65 6d 61 69 6e 20 74 68 65 20 73  all remain the s
1bc0: 61 6d 65 20 61 63 72 6f 73 73 20 63 61 6c 6c 73  ame across calls
1bd0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
1be0: 66 69 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  fig()]..*/.int s
1bf0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1c00: 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  e(void);../*.** 
1c10: 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
1c20: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61  se Connection Ha
1c30: 6e 64 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c 53  ndle {H12000} <S
1c40: 34 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  40200>.** KEYWOR
1c50: 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f  DS: {database co
1c60: 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62  nnection} {datab
1c70: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d  ase connections}
1c80: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e  .**.** Each open
1c90: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
1ca0: 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
1cb0: 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  by a pointer to 
1cc0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a  an instance of.*
1cd0: 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72  * the opaque str
1ce0: 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71  ucture named "sq
1cf0: 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75  lite3".  It is u
1d00: 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f  seful to think o
1d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20  f an sqlite3.** 
1d20: 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62  pointer as an ob
1d30: 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69  ject.  The [sqli
1d40: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1d50: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
1d60: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1d70: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
1d80: 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63  rfaces are its c
1d90: 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64  onstructors, and
1da0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
1db0: 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 73  )].** is its des
1dc0: 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20  tructor.  There 
1dd0: 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69  are many other i
1de0: 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20  nterfaces (such 
1df0: 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  as.** [sqlite3_p
1e00: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
1e10: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
1e20: 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a  nction()], and.*
1e30: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  * [sqlite3_busy_
1e40: 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61  timeout()] to na
1e50: 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68  me but three) th
1e60: 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f  at are methods o
1e70: 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20  n an.** sqlite3 
1e80: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64  object..*/.typed
1e90: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1ea0: 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a  3 sqlite3;../*.*
1eb0: 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42  * CAPI3REF: 64-B
1ec0: 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73  it Integer Types
1ed0: 20 7b 48 31 30 32 30 30 7d 20 3c 53 31 30 31 31   {H10200} <S1011
1ee0: 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
1ef0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
1f00: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
1f10: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
1f20: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
1f30: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
1f40: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
1f50: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
1f60: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
1f70: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
1f80: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
1f90: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
1fa0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
1fb0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
1fc0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
1fd0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
1fe0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
1ff0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2000: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2010: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2020: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2030: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2040: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2050: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2060: 2a 2a 20 7b 48 31 30 32 30 31 7d 20 54 68 65 20  ** {H10201} The 
2070: 5b 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61  [sqlite_int64] a
2080: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36  nd [sqlite3_int6
2090: 34 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70  4] type shall sp
20a0: 65 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20  ecify.**        
20b0: 20 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65    a 64-bit signe
20c0: 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
20d0: 20 7b 48 31 30 32 30 32 7d 20 54 68 65 20 5b 73   {H10202} The [s
20e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e  qlite_uint64] an
20f0: 64 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  d [sqlite3_uint6
2100: 34 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70  4] type shall sp
2110: 65 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20  ecify.**        
2120: 20 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67    a 64-bit unsig
2130: 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a  ned integer..*/.
2140: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
2150: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
2160: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2170: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
2180: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2190: 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54  igned SQLITE_INT
21a0: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
21b0: 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66  int64;.#elif def
21c0: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c  ined(_MSC_VER) |
21d0: 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c  | defined(__BORL
21e0: 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65  ANDC__).  typede
21f0: 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  f __int64 sqlite
2200: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
2210: 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74  f unsigned __int
2220: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2230: 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65  ;.#else.  typede
2240: 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  f long long int 
2250: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
2260: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
2270: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
2280: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2290: 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c  ndif.typedef sql
22a0: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
22b0: 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66  3_int64;.typedef
22c0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73   sqlite_uint64 s
22d0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a  qlite3_uint64;..
22e0: 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69  /*.** If compili
22f0: 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73  ng for a process
2300: 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c  or that lacks fl
2310: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70  oating point sup
2320: 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74  port,.** substit
2330: 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20  ute integer for 
2340: 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a  floating-point..
2350: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
2360: 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50  _OMIT_FLOATING_P
2370: 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f  OINT.# define do
2380: 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  uble sqlite3_int
2390: 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  64.#endif../*.**
23a0: 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69   CAPI3REF: Closi
23b0: 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  ng A Database Co
23c0: 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30  nnection {H12010
23d0: 7d 20 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30  } <S30100><S4020
23e0: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
23f0: 75 74 69 6e 65 20 69 73 20 74 68 65 20 64 65 73  utine is the des
2400: 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
2410: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2420: 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
2430: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c  ions should [sql
2440: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
2450: 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70  finalize] all [p
2460: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2470: 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ts].** and [sqli
2480: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
2490: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
24a0: 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63  B handles] assoc
24b0: 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  iated with.** th
24c0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
24d0: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65  ct prior to atte
24e0: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20  mpting to close 
24f0: 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54  the object..** T
2500: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  he [sqlite3_next
2510: 5f 73 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61  _stmt()] interfa
2520: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
2530: 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20  o locate all.** 
2540: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2550: 65 6e 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64  ents] associated
2560: 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
2570: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66  e connection] if
2580: 20 64 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70   desired..** Typ
2590: 69 63 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20  ical code might 
25a0: 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a  look like this:.
25b0: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
25c0: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74  e><pre>.** sqlit
25d0: 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a  e3_stmt *pStmt;.
25e0: 2a 2a 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74  ** while( (pStmt
25f0: 20 3d 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f   = sqlite3_next_
2600: 73 74 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20  stmt(db, 0))!=0 
2610: 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73  ){.** &nbsp;   s
2620: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2630: 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20  pStmt);.** }.** 
2640: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
2650: 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71  te>.**.** If [sq
2660: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69  lite3_close()] i
2670: 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20  s invoked while 
2680: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2690: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
26a0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
26b0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
26c0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e  d back..**.** IN
26d0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
26e0: 7b 48 31 32 30 31 31 7d 20 41 20 73 75 63 63 65  {H12011} A succe
26f0: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
2700: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
2710: 20 73 68 61 6c 6c 20 64 65 73 74 72 6f 79 20 74   shall destroy t
2720: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2730: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2740: 69 6f 6e 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a  ion] object C..*
2750: 2a 0a 2a 2a 20 7b 48 31 32 30 31 32 7d 20 41 20  *.** {H12012} A 
2760: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
2770: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
2780: 65 28 43 29 5d 20 73 68 61 6c 6c 20 72 65 74 75  e(C)] shall retu
2790: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a  rn SQLITE_OK..**
27a0: 0a 2a 2a 20 7b 48 31 32 30 31 33 7d 20 41 20 73  .** {H12013} A s
27b0: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
27c0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
27d0: 28 43 29 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61  (C)] shall relea
27e0: 73 65 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  se all.**       
27f0: 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79     memory and sy
2800: 73 74 65 6d 20 72 65 73 6f 75 72 63 65 73 20 61  stem resources a
2810: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b  ssociated with [
2820: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2830: 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ion].**         
2840: 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31   C..**.** {H1201
2850: 34 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71  4} A call to [sq
2860: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
2870: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
2880: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 20 74 68 61  onnection] C tha
2890: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61  t.**          ha
28a0: 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70  s one or more op
28b0: 65 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  en [prepared sta
28c0: 74 65 6d 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66  tements] shall f
28d0: 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ail with.**     
28e0: 20 20 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f       an [SQLITE_
28f0: 42 55 53 59 5d 20 65 72 72 6f 72 20 63 6f 64 65  BUSY] error code
2900: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d  ..**.** {H12015}
2910: 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   A call to [sqli
2920: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68  te3_close(C)] wh
2930: 65 72 65 20 43 20 69 73 20 61 20 4e 55 4c 4c 20  ere C is a NULL 
2940: 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a  pointer shall.**
2950: 20 20 20 20 20 20 20 20 20 20 62 65 20 61 20 68            be a h
2960: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 20 72 65  armless no-op re
2970: 74 75 72 6e 69 6e 67 20 53 51 4c 49 54 45 5f 4f  turning SQLITE_O
2980: 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 39  K..**.** {H12019
2990: 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  } When [sqlite3_
29a0: 63 6c 6f 73 65 28 43 29 5d 20 69 73 20 69 6e 76  close(C)] is inv
29b0: 6f 6b 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62  oked on a [datab
29c0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
29d0: 43 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  C.**          th
29e0: 61 74 20 68 61 73 20 61 20 70 65 6e 64 69 6e 67  at has a pending
29f0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
2a00: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73 68  e transaction sh
2a10: 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20  all be.**       
2a20: 20 20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a     rolled back..
2a30: 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
2a40: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 30 31 36  S:.**.** {A12016
2a50: 7d 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65  } The C paramete
2a60: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  r to [sqlite3_cl
2a70: 6f 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65 20  ose(C)] must be 
2a80: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
2a90: 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65            pointe
2aa0: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
2ab0: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
2ac0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20   obtained.**    
2ad0: 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69        from [sqli
2ae0: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
2af0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
2b00: 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2b10: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2b20: 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65  ()], and not pre
2b30: 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a  viously closed..
2b40: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2b50: 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b  lose(sqlite3 *);
2b60: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ../*.** The type
2b70: 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20   for a callback 
2b80: 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69  function..** Thi
2b90: 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20  s is legacy and 
2ba0: 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20  deprecated.  It 
2bb0: 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20  is included for 
2bc0: 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f  historical.** co
2bd0: 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20  mpatibility and 
2be0: 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65  is not documente
2bf0: 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e  d..*/.typedef in
2c00: 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c  t (*sqlite3_call
2c10: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
2c20: 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b  char**, char**);
2c30: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c40: 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79  : One-Step Query
2c50: 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72   Execution Inter
2c60: 66 61 63 65 20 7b 48 31 32 31 30 30 7d 20 3c 53  face {H12100} <S
2c70: 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  10000>.**.** The
2c80: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
2c90: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
2ca0: 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f 66  onvenient way of
2cb0: 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20   running one or 
2cc0: 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74  more.** SQL stat
2cd0: 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20 68  ements without h
2ce0: 61 76 69 6e 67 20 74 6f 20 77 72 69 74 65 20 61  aving to write a
2cf0: 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20   lot of C code. 
2d00: 20 54 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   The UTF-8 encod
2d10: 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
2d20: 65 6e 74 73 20 61 72 65 20 70 61 73 73 65 64 20  ents are passed 
2d30: 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  in as the second
2d40: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2d50: 6c 69 74 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a  lite3_exec()..**
2d60: 20 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20   The statements 
2d70: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 6f 6e  are evaluated on
2d80: 65 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65  e by one until e
2d90: 69 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f  ither an error o
2da0: 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 75 70  r.** an interrup
2db0: 74 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65 64  t is encountered
2dc0: 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 79 20  , or until they 
2dd0: 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54  are all done.  T
2de0: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2df0: 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e  .** is an option
2e00: 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74  al callback that
2e10: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
2e20: 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66   for each row of
2e30: 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20 72 65   any query.** re
2e40: 73 75 6c 74 73 20 70 72 6f 64 75 63 65 64 20 62  sults produced b
2e50: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
2e60: 65 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20 70  ents.  The 5th p
2e70: 61 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77  arameter tells w
2e80: 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65  here.** to write
2e90: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
2ea0: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65  ges..**.** The e
2eb0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61 73  rror message pas
2ec0: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68  sed back through
2ed0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
2ee0: 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e  er is held.** in
2ef0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
2f00: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2f10: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76  alloc()].  To av
2f20: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
2f30: 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e  k,.** the callin
2f40: 67 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  g application sh
2f50: 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74  ould call [sqlit
2f60: 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e  e3_free()] on an
2f70: 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  y error.** messa
2f80: 67 65 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  ge returned thro
2f90: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
2fa0: 6d 65 74 65 72 20 77 68 65 6e 20 69 74 20 68 61  meter when it ha
2fb0: 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
2fc0: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
2fd0: 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ssage..**.** If 
2fe0: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2ff0: 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72  t in the 2nd par
3000: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f  ameter is NULL o
3010: 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
3020: 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e 67  g.** or a string
3030: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79   containing only
3040: 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 20   whitespace and 
3050: 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e  comments, then n
3060: 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  o SQL.** stateme
3070: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3080: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3090: 73 65 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  se is not change
30a0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
30b0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
30c0: 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
30d0: 6e 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f 66  nted in terms of
30e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
30f0: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
3100: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e  ite3_step()], an
3110: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
3120: 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  ize()]..** The s
3130: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72 6f  qlite3_exec() ro
3140: 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69  utine does nothi
3150: 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ng to the databa
3160: 73 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  se that cannot b
3170: 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71  e done.** by [sq
3180: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
3190: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
31a0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
31b0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
31c0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
31d0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 31  S:.**.** {H12101
31e0: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
31f0: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
3200: 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43  lite3_exec(D,S,C
3210: 2c 41 2c 45 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,A,E)].**       
3220: 20 20 20 73 68 61 6c 6c 20 73 65 71 75 65 6e 74     shall sequent
3230: 69 61 6c 6c 79 20 65 76 61 6c 75 61 74 65 20 61  ially evaluate a
3240: 6c 6c 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20  ll of the UTF-8 
3250: 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 20 20 20 20  encoded,.**     
3260: 20 20 20 20 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73       semicolon-s
3270: 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
3280: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
3290: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
32a0: 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
32b0: 67 20 53 20 77 69 74 68 69 6e 20 74 68 65 20 63  g S within the c
32c0: 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64  ontext of the [d
32d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32e0: 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  on] D..**.** {H1
32f0: 32 31 30 32 7d 20 49 66 20 74 68 65 20 53 20 70  2102} If the S p
3300: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
3310: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c  ite3_exec(D,S,C,
3320: 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68  A,E)] is NULL th
3330: 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  en.**          t
3340: 68 65 20 61 63 74 69 6f 6e 73 20 6f 66 20 74 68  he actions of th
3350: 65 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  e interface shal
3360: 6c 20 62 65 20 74 68 65 20 73 61 6d 65 20 61 73  l be the same as
3370: 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   if the.**      
3380: 20 20 20 20 53 20 70 61 72 61 6d 65 74 65 72 20      S parameter 
3390: 77 65 72 65 20 61 6e 20 65 6d 70 74 79 20 73 74  were an empty st
33a0: 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ring..**.** {H12
33b0: 31 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20  104} The return 
33c0: 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
33d0: 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20  3_exec()] shall 
33e0: 62 65 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  be [SQLITE_OK] i
33f0: 66 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  f all.**        
3400: 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73    SQL statements
3410: 20 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c 6c   run successfull
3420: 79 20 61 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74  y and to complet
3430: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ion..**.** {H121
3440: 30 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  05} The return v
3450: 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
3460: 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62  _exec()] shall b
3470: 65 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  e an appropriate
3480: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 6e  .**          non
3490: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
34a0: 65 5d 20 69 66 20 61 6e 79 20 53 51 4c 20 73 74  e] if any SQL st
34b0: 61 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a  atement fails..*
34c0: 2a 0a 2a 2a 20 7b 48 31 32 31 30 37 7d 20 49 66  *.** {H12107} If
34d0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
34e0: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
34f0: 74 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71  ts handed to [sq
3500: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a  lite3_exec()].**
3510: 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
3520: 20 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68 65   results and the
3530: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
3540: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
3550: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
3560: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3570: 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
3580: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
3590: 72 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20  r shall be.**   
35a0: 20 20 20 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f         invoked o
35b0: 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77  nce for each row
35c0: 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a   of result..**.*
35d0: 2a 20 7b 48 31 32 31 31 30 7d 20 49 66 20 74 68  * {H12110} If th
35e0: 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
35f0: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61  ns a non-zero va
3600: 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  lue then [sqlite
3610: 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20  3_exec()].**    
3620: 20 20 20 20 20 20 73 68 61 6c 6c 20 61 62 6f 72        shall abor
3630: 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
3640: 65 6e 74 20 69 74 20 69 73 20 63 75 72 72 65 6e  ent it is curren
3650: 74 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a  tly evaluating,.
3660: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69 70  **          skip
3670: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
3680: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20  SQL statements, 
3690: 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
36a0: 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a  TE_ABORT]..**.**
36b0: 20 7b 48 31 32 31 31 33 7d 20 54 68 65 20 5b 73   {H12113} The [s
36c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
36d0: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 70 61 73  outine shall pas
36e0: 73 20 69 74 73 20 34 74 68 20 70 61 72 61 6d 65  s its 4th parame
36f0: 74 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20  ter through.**  
3700: 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20 31          as the 1
3710: 73 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  st parameter of 
3720: 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
3730: 0a 2a 2a 20 7b 48 31 32 31 31 36 7d 20 54 68 65  .** {H12116} The
3740: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3750: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
3760: 73 65 74 20 74 68 65 20 32 6e 64 20 70 61 72 61  set the 2nd para
3770: 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20  meter of its.** 
3780: 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
3790: 6b 20 74 6f 20 62 65 20 74 68 65 20 6e 75 6d 62  k to be the numb
37a0: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
37b0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
37c0: 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
37d0: 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  result..**.** {H
37e0: 31 32 31 31 39 7d 20 54 68 65 20 5b 73 71 6c 69  12119} The [sqli
37f0: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74  te3_exec()] rout
3800: 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68  ine shall set th
3810: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
3820: 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  of its.**       
3830: 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62     callback to b
3840: 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  e an array of po
3850: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3860: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a  s holding the.**
3870: 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 73            values
3880: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3890: 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
38a0: 72 65 73 75 6c 74 20 73 65 74 20 72 6f 77 20 61  result set row a
38b0: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  s.**          ob
38c0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
38d0: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
38e0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ()]..**.** {H121
38f0: 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  22} The [sqlite3
3900: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65  _exec()] routine
3910: 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 34   shall set the 4
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
3930: 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
3940: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61  callback to be a
3950: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3960: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68  ers to strings h
3970: 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  olding the.**   
3980: 20 20 20 20 20 20 20 6e 61 6d 65 73 20 6f 66 20         names of 
3990: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 61  result columns a
39a0: 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
39b0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
39c0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  name()]..**.** {
39d0: 48 31 32 31 32 35 7d 20 49 66 20 74 68 65 20 33  H12125} If the 3
39e0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
39f0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3a00: 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a   is NULL then.**
3a10: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
3a20: 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c  e3_exec()] shall
3a30: 20 73 69 6c 65 6e 74 6c 79 20 64 69 73 63 61 72   silently discar
3a40: 64 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  d query results.
3a50: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 31 7d 20  .**.** {H12131} 
3a60: 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  If an error occu
3a70: 72 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67  rs while parsing
3a80: 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 61   or evaluating a
3a90: 6e 79 20 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a  ny of the SQL.**
3aa0: 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d            statem
3ab0: 65 6e 74 73 20 69 6e 20 74 68 65 20 53 20 70 61  ents in the S pa
3ac0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
3ad0: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41  te3_exec(D,S,C,A
3ae0: 2c 45 29 5d 20 61 6e 64 20 69 66 0a 2a 2a 20 20  ,E)] and if.**  
3af0: 20 20 20 20 20 20 20 20 74 68 65 20 45 20 70 61          the E pa
3b00: 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e  rameter is not N
3b10: 55 4c 4c 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74  ULL, then [sqlit
3b20: 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c  e3_exec()] shall
3b30: 20 73 74 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20   store.**       
3b40: 20 20 20 69 6e 20 2a 45 20 61 6e 20 61 70 70 72     in *E an appr
3b50: 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65  opriate error me
3b60: 73 73 61 67 65 20 77 72 69 74 74 65 6e 20 69 6e  ssage written in
3b70: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
3b80: 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ed.**          f
3b90: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
3ba0: 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  loc()]..**.** {H
3bb0: 31 32 31 33 34 7d 20 54 68 65 20 5b 73 71 6c 69  12134} The [sqli
3bc0: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41  te3_exec(D,S,C,A
3bd0: 2c 45 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61  ,E)] routine sha
3be0: 6c 6c 20 73 65 74 20 74 68 65 20 76 61 6c 75 65  ll set the value
3bf0: 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
3c00: 2a 45 20 74 6f 20 4e 55 4c 4c 20 69 66 20 45 20  *E to NULL if E 
3c10: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20  is not NULL and 
3c20: 74 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72 72  there are no err
3c30: 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ors..**.** {H121
3c40: 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  37} The [sqlite3
3c50: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3c60: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c  ] function shall
3c70: 20 73 65 74 20 74 68 65 20 5b 65 72 72 6f 72 20   set the [error 
3c80: 63 6f 64 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20  code].**        
3c90: 20 20 61 6e 64 20 6d 65 73 73 61 67 65 20 61 63    and message ac
3ca0: 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71  cessible via [sq
3cb0: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
3cc0: 2c 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  , .**          [
3cd0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
3ce0: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
3cf0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3d00: 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64  3_errmsg()], and
3d10: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3d20: 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  16()]..**.** {H1
3d30: 32 31 33 38 7d 20 49 66 20 74 68 65 20 53 20 70  2138} If the S p
3d40: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
3d50: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c  ite3_exec(D,S,C,
3d60: 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72  A,E)] is NULL or
3d70: 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
3d80: 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
3d90: 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67  contains nothing
3da0: 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74   other than whit
3db0: 65 73 70 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73  espace, comments
3dc0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  ,.**          an
3dd0: 64 2f 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c  d/or semicolons,
3de0: 20 74 68 65 6e 20 72 65 73 75 6c 74 73 20 6f 66   then results of
3df0: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
3e00: 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  e()],.**        
3e10: 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e    [sqlite3_exten
3e20: 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a  ded_errcode()],.
3e30: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3e40: 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20  ite3_errmsg()], 
3e50: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
3e60: 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  msg16()].**     
3e70: 20 20 20 20 20 73 68 61 6c 6c 20 72 65 73 65 74       shall reset
3e80: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f 20   to indicate no 
3e90: 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53  errors..**.** AS
3ea0: 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
3eb0: 20 7b 41 31 32 31 34 31 7d 20 54 68 65 20 66 69   {A12141} The fi
3ec0: 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
3ed0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3ee0: 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c  ] must be an val
3ef0: 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20  id and open.**  
3f00: 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
3f10: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
3f20: 2a 0a 2a 2a 20 7b 41 31 32 31 34 32 7d 20 54 68  *.** {A12142} Th
3f30: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
3f40: 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62  ction must not b
3f50: 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a  e closed while.*
3f60: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
3f70: 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72  te3_exec()] is r
3f80: 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41  unning..**.** {A
3f90: 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c 6c 69  12143} The calli
3fa0: 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ng function shou
3fb0: 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f  ld use [sqlite3_
3fc0: 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65 0a  free()] to free.
3fd0: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
3fe0: 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72  memory that *err
3ff0: 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  msg is left poin
4000: 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65  ting at once the
4010: 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20   error.**       
4020: 20 20 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f     message is no
4030: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
4040: 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54  **.** {A12145} T
4050: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
4060: 20 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64   text in the 2nd
4070: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
4080: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a  qlite3_exec()].*
4090: 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20  *          must 
40a0: 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
40b0: 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
40c0: 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69  exec()] is runni
40d0: 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
40e0: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  e3_exec(.  sqlit
40f0: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
4120: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
4130: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
4140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4150: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
4160: 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
4170: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c   */.  int (*call
4180: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
4190: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20  char**,char**), 
41a0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e   /* Callback fun
41b0: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
41c0: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67        /* 1st arg
41f0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63  ument to callbac
4200: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  k */.  char **er
4210: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20  rmsg            
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4230: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
4240: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
4250: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
4260: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  F: Result Codes 
4270: 7b 48 31 30 32 31 30 7d 20 3c 53 31 30 37 30 30  {H10210} <S10700
4280: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  >.** KEYWORDS: S
4290: 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20  QLITE_OK {error 
42a0: 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64  code} {error cod
42b0: 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
42c0: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b   {result code} {
42d0: 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a  result codes}.**
42e0: 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20  .** Many SQLite 
42f0: 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
4300: 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75   an integer resu
4310: 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65  lt code from the
4320: 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65   set shown.** he
4330: 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69  re in order to i
4340: 6e 64 69 63 61 74 65 73 20 73 75 63 63 65 73 73  ndicates success
4350: 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a   or failure..**.
4360: 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64  ** New error cod
4370: 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
4380: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
4390: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
43a0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53  .** See also: [S
43b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
43c0: 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
43d0: 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65  lt codes].*/.#de
43e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20  fine SQLITE_OK  
43f0: 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
4400: 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c  Successful resul
4410: 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e  t */./* beginnin
4420: 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  g-of-error-codes
4430: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4440: 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20  TE_ERROR        
4450: 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72  1   /* SQL error
4460: 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61   or missing data
4470: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
4480: 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20  SQLITE_INTERNAL 
4490: 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72      2   /* Inter
44a0: 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20  nal logic error 
44b0: 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65  in SQLite */.#de
44c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d  fine SQLITE_PERM
44d0: 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20           3   /* 
44e0: 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f  Access permissio
44f0: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
4500: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
4510: 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43          4   /* C
4520: 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
4530: 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f  requested an abo
4540: 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  rt */.#define SQ
4550: 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20  LITE_BUSY       
4560: 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74    5   /* The dat
4570: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f  abase file is lo
4580: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4590: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20  SQLITE_LOCKED   
45a0: 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62      6   /* A tab
45b0: 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61  le in the databa
45c0: 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  se is locked */.
45d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
45e0: 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20  OMEM        7   
45f0: 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61  /* A malloc() fa
4600: 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  iled */.#define 
4610: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
4620: 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d      8   /* Attem
4630: 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65  pt to write a re
4640: 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20  adonly database 
4650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4660: 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39  E_INTERRUPT    9
4670: 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
4680: 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71  terminated by sq
4690: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
46a0: 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )*/.#define SQLI
46b0: 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31  TE_IOERR       1
46c0: 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64  0   /* Some kind
46d0: 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72   of disk I/O err
46e0: 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23  or occurred */.#
46f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
4700: 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f  RRUPT     11   /
4710: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64  * The database d
4720: 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c  isk image is mal
4730: 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e  formed */.#defin
4740: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  e SQLITE_NOTFOUN
4750: 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54  D    12   /* NOT
4760: 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20   USED. Table or 
4770: 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64  record not found
4780: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4790: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
47a0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
47b0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
47c0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
47d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
47f0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4800: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4810: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4820: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4830: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f  OL    15   /* NO
4840: 54 20 55 53 45 44 2e 20 44 61 74 61 62 61 73 65  T USED. Database
4850: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
4860: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4870: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4880: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
4890: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
48a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
48b0: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
48c0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
48d0: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
48e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
48f0: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4900: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4910: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
4920: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
4930: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
4940: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
4950: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
4960: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
4970: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4980: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4990: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
49a0: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
49b0: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
49c0: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
49d0: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
49e0: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
49f0: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4a00: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4a10: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
4a20: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
4a30: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
4a40: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
4a50: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
4a60: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
4a70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4a80: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4a90: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4aa0: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4ab0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4ac0: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4ad0: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4ae0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4af0: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4b00: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4b10: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4b20: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4b30: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4b40: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4b50: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4b60: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4b70: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4b80: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4b90: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4ba0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4bb0: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4bc0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4bd0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4be0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4bf0: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4c00: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4c10: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4c20: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48   Result Codes {H
4c30: 31 30 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a  10220} <S10700>.
4c40: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78  ** KEYWORDS: {ex
4c50: 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
4c60: 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72  e} {extended err
4c70: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4c80: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4c90: 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65   result code} {e
4ca0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4cb0: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69  odes}.**.** In i
4cc0: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ts default confi
4cd0: 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65  guration, SQLite
4ce0: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
4cf0: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69  turn one of 26 i
4d00: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
4d10: 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
4d20: 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20  des].  However, 
4d30: 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73  experience has s
4d40: 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f  hown that many o
4d50: 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c  f.** these resul
4d60: 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20  t codes are too 
4d70: 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20  coarse-grained. 
4d80: 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f   They do not pro
4d90: 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20  vide as.** much 
4da0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
4db0: 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72  t problems as pr
4dc0: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
4dd0: 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66  like.  In an eff
4de0: 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73  ort to.** addres
4df0: 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65  s this, newer ve
4e00: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
4e10: 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20   (version 3.3.8 
4e20: 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75  and later) inclu
4e30: 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f  de.** support fo
4e40: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73  r additional res
4e50: 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70  ult codes that p
4e60: 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61  rovide more deta
4e70: 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  iled information
4e80: 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73  .** about errors
4e90: 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72  . The extended r
4ea0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4eb0: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
4ec0: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
4ed0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4ee0: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
4ef0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4f00: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
4f10: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a  codes()] API..**
4f20: 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20  .** Some of the 
4f30: 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64  available extend
4f40: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4f50: 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e  are listed here.
4f60: 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65  .** One may expe
4f70: 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ct the number of
4f80: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4f90: 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65   codes will be e
4fa0: 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69  xpand.** over ti
4fb0: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  me.  Software th
4fc0: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64  at uses extended
4fd0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68   result codes sh
4fe0: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74  ould expect.** t
4ff0: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74  o see new result
5000: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65   codes in future
5010: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
5020: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ite..**.** The S
5030: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
5040: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
5050: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
5060: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
5070: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
5080: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
5090: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33  S:.**.** {H10223
50a0: 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e  } The symbolic n
50b0: 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e  ame for an exten
50c0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
50d0: 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a  shall contains.*
50e0: 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65 6c  *          a rel
50f0: 61 74 65 64 20 70 72 69 6d 61 72 79 20 72 65 73  ated primary res
5100: 75 6c 74 20 63 6f 64 65 20 61 73 20 61 20 70 72  ult code as a pr
5110: 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  efix..**.** {H10
5120: 32 32 34 7d 20 50 72 69 6d 61 72 79 20 72 65 73  224} Primary res
5130: 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73  ult code names s
5140: 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73  hall contain a s
5150: 69 6e 67 6c 65 20 22 5f 22 20 63 68 61 72 61 63  ingle "_" charac
5160: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  ter..**.** {H102
5170: 32 35 7d 20 45 78 74 65 6e 64 65 64 20 72 65 73  25} Extended res
5180: 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73  ult code names s
5190: 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f  hall contain two
51a0: 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61   or more "_" cha
51b0: 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b  racters..**.** {
51c0: 48 31 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65  H10226} The nume
51d0: 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20  ric value of an 
51e0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
51f0: 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61  code shall conta
5200: 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
5210: 20 20 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65     numeric value
5220: 20 6f 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f   of its correspo
5230: 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65  nding primary re
5240: 73 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20  sult code in.** 
5250: 20 20 20 20 20 20 20 20 20 69 74 73 20 6c 65 61           its lea
5260: 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38  st significant 8
5270: 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e   bits..*/.#defin
5280: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
5290: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
52a0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
52b0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
52c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
52d0: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20  ORT_READ        
52e0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52f0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5300: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
5310: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  TE             (
5320: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5330: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5340: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
5350: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  C             (S
5360: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
5370: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5380: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
5390: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51  SYNC         (SQ
53a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c  LITE_IOERR | (5<
53b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53c0: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41  ITE_IOERR_TRUNCA
53d0: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TE          (SQL
53e0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
53f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5400: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
5410: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5420: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
5430: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5440: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
5450: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5460: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
5470: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5480: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
5490: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
54a0: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29  _IOERR | (9<<8))
54b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54c0: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20  IOERR_DELETE    
54d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
54e0: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
54f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5500: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
5510: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5520: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
5530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5540: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
5550: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5560: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
5570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5580: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20  IOERR_ACCESS    
5590: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
55a0: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29  IOERR | (13<<8))
55b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55c0: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52  IOERR_CHECKRESER
55d0: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f  VEDLOCK (SQLITE_
55e0: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29  IOERR | (14<<8))
55f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5600: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20  IOERR_LOCK      
5610: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5620: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29  IOERR | (15<<8))
5630: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5640: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20  IOERR_CLOSE     
5650: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5660: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29  IOERR | (16<<8))
5670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5680: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20  IOERR_DIR_CLOSE 
5690: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56a0: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29  IOERR | (17<<8))
56b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
56c0: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
56d0: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
56e0: 20 7b 48 31 30 32 33 30 7d 20 3c 48 31 31 31 32   {H10230} <H1112
56f0: 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a  0> <H12700>.**.*
5700: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5710: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5720: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5730: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5740: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5750: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5760: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5770: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5780: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
5790: 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  thod of the.** [
57a0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
57b0: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
57c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
57d0: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30  ONLY         0x0
57e0: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
57f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5800: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30  WRITE        0x0
5810: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
5820: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
5830: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30  TE           0x0
5840: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
5850: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
5860: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30  TEONCLOSE    0x0
5870: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
5880: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
5890: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30  USIVE        0x0
58a0: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
58b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
58c0: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
58d0: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
58e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
58f0: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5900: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
5910: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
5920: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30  SIENT_DB     0x0
5930: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
5940: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5950: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
5960: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20  0000800.#define 
5970: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5980: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
5990: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
59a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
59b0: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30  OURNAL       0x0
59c0: 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20  0002000.#define 
59d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
59e0: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30  ER_JOURNAL   0x0
59f0: 30 30 30 34 30 30 30 0a 23 64 65 66 69 6e 65 20  0004000.#define 
5a00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
5a10: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30  TEX          0x0
5a20: 30 30 30 38 30 30 30 0a 23 64 65 66 69 6e 65 20  0008000.#define 
5a30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
5a40: 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30  MUTEX        0x0
5a50: 30 30 31 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0010000../*.** C
5a60: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
5a70: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
5a80: 7b 48 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30  {H10240} <H11120
5a90: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  >.**.** The xDev
5aa0: 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 20  iceCapabilities 
5ab0: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
5ac0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5ad0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
5ae0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
5af0: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
5b00: 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a  r of the these.*
5b10: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
5b20: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
5b30: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
5b40: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
5b50: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
5b60: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
5b70: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
5b80: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
5b90: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
5ba0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5bb0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
5bc0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
5bd0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
5be0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
5bf0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
5c00: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
5c10: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
5c20: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
5c30: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
5c40: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
5c50: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
5c60: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
5c70: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
5c80: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
5c90: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
5ca0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
5cb0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
5cc0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
5cd0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
5ce0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
5cf0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
5d00: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
5d10: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
5d20: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
5d30: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
5d40: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
5d50: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
5d60: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
5d70: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
5d80: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
5d90: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
5da0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
5db0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
5dc0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
5dd0: 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ite()..*/.#defin
5de0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5df0: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 30  TOMIC          0
5e00: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
5e10: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5e20: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 30  TOMIC512       0
5e30: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
5e40: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5e50: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30  TOMIC1K        0
5e60: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
5e70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5e80: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30  TOMIC2K        0
5e90: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
5ea0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5eb0: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30  TOMIC4K        0
5ec0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
5ed0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5ee0: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30  TOMIC8K        0
5ef0: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
5f00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5f10: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30  TOMIC16K       0
5f20: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e  x00000040.#defin
5f30: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5f40: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30  TOMIC32K       0
5f50: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
5f60: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5f70: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30  TOMIC64K       0
5f80: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
5f90: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5fa0: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30  AFE_APPEND     0
5fb0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
5fc0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5fd0: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30  EQUENTIAL      0
5fe0: 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a  x00000400../*.**
5ff0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
6000: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b  Locking Levels {
6010: 48 31 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e  H10250} <H11120>
6020: 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20   <H11310>.**.** 
6030: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
6040: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
6050: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6060: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
6070: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
6080: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
6090: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
60a0: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
60b0: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
60c0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
60d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60e0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
60f0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
6100: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
6110: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
6120: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
6130: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
6140: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6150: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
6160: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6170: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
6180: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
6190: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
61a0: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
61b0: 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31  s {H10260} <H111
61c0: 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  20>.**.** When S
61d0: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
61e0: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
61f0: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
6200: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6210: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
6220: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6230: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6240: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6250: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
6260: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
6270: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6280: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
6290: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
62a0: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
62b0: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
62c0: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
62d0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
62e0: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
62f0: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
6300: 20 66 6c 75 73 68 65 64 2e 20 54 68 65 20 53 51   flushed. The SQ
6310: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6320: 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74   flag means.** t
6330: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
6340: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 20  nc() semantics. 
6350: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
6360: 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a  FULL flag means.
6370: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
6380: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
6390: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
63a0: 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nc()..*/.#define
63b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
63c0: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
63d0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
63e0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
63f0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
6400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
6410: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
6420: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
6430: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
6440: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
6450: 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c  andle {H11110} <
6460: 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e  S20110>.**.** An
6470: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
6480: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
6490: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
64a0: 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65  n the OS.** inte
64b0: 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e  rface layer.  In
64c0: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
64d0: 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61  rface implementa
64e0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
64f0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
6500: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
6510: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
6520: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
6530: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
6540: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
6550: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
6560: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
6570: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6580: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
6590: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
65a0: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
65b0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
65c0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
65d0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
65e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
65f0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
6600: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
6610: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
6620: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6630: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
6640: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
6650: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
6660: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6670: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
6680: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
6690: 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31  ods Object {H111
66a0: 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a  20} <S20110>.**.
66b0: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
66c0: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
66d0: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
66e0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
66f0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6700: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
6710: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
6720: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
6730: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
6740: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
6750: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
6760: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
6770: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
6780: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
6790: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
67a0: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
67b0: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
67c0: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
67d0: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
67e0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
67f0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6800: 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  ct..**.** The fl
6810: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
6820: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
6830: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
6840: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
6850: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6860: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
6870: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
6880: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
6890: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
68a0: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
68b0: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
68c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
68d0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
68e0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
68f0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
6900: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
6910: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
6920: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
6930: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
6940: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
6950: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
6960: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
6970: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
6980: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
6990: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
69a0: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
69b0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
69c0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
69d0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
69e0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
69f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6a00: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
6a10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
6a20: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
6a30: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
6a40: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
6a50: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
6a60: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
6a70: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
6a80: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
6a90: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
6aa0: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
6ab0: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
6ac0: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
6ad0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
6ae0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
6af0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
6b00: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
6b10: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
6b20: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
6b30: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
6b40: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
6b50: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
6b60: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
6b70: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
6b80: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
6b90: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
6ba0: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
6bb0: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
6bc0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
6bd0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
6be0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
6bf0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
6c00: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
6c10: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
6c20: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
6c30: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
6c40: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
6c50: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
6c60: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
6c70: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
6c80: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
6c90: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
6ca0: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
6cb0: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
6cc0: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
6cd0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
6ce0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
6cf0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
6d00: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
6d10: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
6d20: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
6d30: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
6d40: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
6d50: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
6d60: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
6d70: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
6d80: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
6d90: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
6da0: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
6db0: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
6dc0: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
6dd0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
6de0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
6df0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
6e00: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
6e10: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
6e20: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
6e30: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
6e40: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
6e50: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
6e60: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
6e70: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
6e80: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
6e90: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
6ea0: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
6eb0: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
6ec0: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
6ed0: 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a   conflicts..**.*
6ee0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
6ef0: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
6f00: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
6f10: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
6f20: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
6f30: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
6f40: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
6f50: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
6f60: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
6f70: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
6f80: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
6f90: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
6fa0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
6fb0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
6fc0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
6fd0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
6fe0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
6ff0: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
7000: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
7010: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
7020: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
7030: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7040: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
7050: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
7060: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
7070: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7080: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
7090: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
70a0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
70b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
70c0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
70d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
70e0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
70f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7100: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
7110: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7120: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
7130: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7140: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
7150: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
7160: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
7170: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7180: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
7190: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
71a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
71b0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
71c0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
71d0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
71e0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
71f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7200: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
7210: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
7220: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
7230: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
7240: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
7250: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
7260: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
7270: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
7280: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
7290: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
72a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
72b0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
72c0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
72d0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
72e0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
72f0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
7300: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
7310: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
7320: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
7330: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
7340: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
7350: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
7360: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
7370: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7380: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
7390: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
73a0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
73b0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
73c0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
73d0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
73e0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
73f0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
7400: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
7410: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
7420: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
7430: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
7440: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
7450: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
7460: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
7470: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
7480: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
7490: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
74a0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
74b0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
74c0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
74d0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
74e0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
74f0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7500: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
7510: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7520: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7530: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
7540: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
7550: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
7560: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7570: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
7580: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
7590: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
75a0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
75b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
75c0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
75d0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
75e0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
75f0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
7600: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
7610: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7620: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
7630: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
7640: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
7650: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
7660: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
7670: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7680: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7690: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
76a0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
76b0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
76c0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
76d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
76e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
76f0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
7700: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7710: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
7720: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
7730: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
7740: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
7750: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
7760: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
7770: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
7780: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
7790: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
77a0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
77b0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
77c0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
77d0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
77e0: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
77f0: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
7800: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
7810: 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30   Opcodes {H11310
7820: 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a  } <S30800>.**.**
7830: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
7840: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
7850: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
7860: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7870: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
7880: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7890: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
78a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
78b0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
78c0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
78d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
78e0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
78f0: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
7900: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
7910: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
7920: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
7930: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
7940: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
7950: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
7960: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
7970: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
7980: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
7990: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
79a0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
79b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
79c0: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
79d0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
79e0: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
79f0: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
7a00: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
7a10: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
7a20: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
7a30: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
7a40: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
7a50: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
7a60: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
7a70: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
7a80: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
7a90: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
7aa0: 41 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65  ATE        1.#de
7ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
7ac0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
7ad0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
7ae0: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
7af0: 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65  YFILE      3.#de
7b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
7b10: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
7b20: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
7b30: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
7b40: 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30  le {H17110} <S20
7b50: 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  130>.**.** The m
7b60: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
7b70: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
7b80: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
7b90: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
7ba0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
7bb0: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
7bc0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
7bd0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
7be0: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
7bf0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
7c00: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
7c10: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
7c20: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
7c30: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
7c40: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
7c50: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
7c60: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
7c70: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
7c80: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
7c90: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
7ca0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
7cb0: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
7cc0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
7cd0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
7ce0: 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31  t {H11140} <S201
7cf0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  00>.**.** An ins
7d00: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
7d10: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
7d20: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
7d30: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
7d40: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
7d50: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
7d60: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
7d70: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
7d80: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
7d90: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
7da0: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
7db0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
7dc0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
7dd0: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
7de0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
7df0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
7e00: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
7e10: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
7e20: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
7e30: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
7e40: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
7e50: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
7e60: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
7e70: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
7e80: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
7e90: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
7ea0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
7eb0: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
7ec0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
7ed0: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
7ee0: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
7ef0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
7f00: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
7f10: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
7f20: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
7f30: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
7f40: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
7f50: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
7f60: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7f70: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7f80: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7f90: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
7fa0: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
7fb0: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
7fc0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
7fd0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
7fe0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
7ff0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
8000: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
8010: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
8020: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
8030: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
8040: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
8050: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
8060: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
8070: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
8080: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
8090: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
80a0: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
80b0: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
80c0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
80d0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
80e0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
80f0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
8100: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
8110: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
8120: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
8130: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
8140: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
8150: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
8160: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
8170: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
8180: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
8190: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
81a0: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
81b0: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
81c0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
81d0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
81e0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
81f0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
8200: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
8210: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
8220: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
8230: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
8240: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
8250: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
8260: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
8270: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
8280: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
8290: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
82a0: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
82b0: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
82c0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
82d0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
82e0: 2a 2a 20 7b 48 31 31 31 34 31 7d 20 53 51 4c 69  ** {H11141} SQLi
82f0: 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65  te will guarante
8300: 65 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65  e that the zFile
8310: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
8320: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69  o xOpen.** is ei
8330: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
8340: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62  ter or string ob
8350: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78  tained.** from x
8360: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20  FullPathname(). 
8370: 20 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20   SQLite further 
8380: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
8390: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
83a0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
83b0: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
83c0: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
83d0: 61 6c 6c 65 64 2e 20 7b 45 4e 44 7d 20 20 42 65  alled. {END}  Be
83e0: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
83f0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a  vious sentense,.
8400: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
8410: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
8420: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
8430: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
8440: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
8450: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
8460: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
8470: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
8480: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
8490: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
84a0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
84b0: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
84c0: 20 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74 73   must invite its
84d0: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
84e0: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
84f0: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
8500: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
8510: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
8520: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
8530: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
8540: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
8550: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
8560: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
8570: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
8580: 2a 0a 2a 2a 20 7b 48 31 31 31 34 32 7d 20 54 68  *.** {H11142} Th
8590: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
85a0: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c   to xOpen() incl
85b0: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65  udes all bits se
85c0: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67  t in.** the flag
85d0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  s argument to [s
85e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
85f0: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74  ].  Or if [sqlit
8600: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72  e3_open()].** or
8610: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
8620: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65  ()] is used, the
8630: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73  n flags includes
8640: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51   at least.** [SQ
8650: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
8660: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
8670: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e  PEN_CREATE]. {EN
8680: 44 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  D}.** If xOpen()
8690: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
86a0: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
86b0: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
86c0: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
86d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
86e0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
86f0: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
8700: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
8710: 2a 20 7b 48 31 31 31 34 33 7d 20 53 51 4c 69 74  * {H11143} SQLit
8720: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
8730: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
8740: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
8750: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
8760: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
8770: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
8780: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
8790: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
87a0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
87b0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
87c0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
87d0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
87e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
87f0: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
8800: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
8810: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
8820: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8830: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
8840: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
8850: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
8860: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8870: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
8880: 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b  RNAL].** </ul> {
8890: 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  END}.**.** The f
88a0: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
88b0: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
88c0: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
88d0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
88e0: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
88f0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
8900: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
8910: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
8920: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
8930: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
8940: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
8950: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
8960: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
8970: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
8980: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
8990: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
89a0: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
89b0: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
89c0: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
89d0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
89e0: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
89f0: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
8a00: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
8a10: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
8a20: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
8a30: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
8a40: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
8a50: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
8a60: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
8a70: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
8a80: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
8a90: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
8aa0: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
8ab0: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
8ac0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
8ad0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
8ae0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
8af0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
8b00: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8b10: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8b20: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
8b30: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8b40: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
8b50: 2a 2a 20 7b 48 31 31 31 34 35 7d 20 54 68 65 20  ** {H11145} The 
8b60: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
8b70: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
8b80: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
8b90: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
8ba0: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
8bb0: 63 6c 6f 73 65 64 2e 20 20 7b 48 31 31 31 34 36  closed.  {H11146
8bc0: 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  } The [SQLITE_OP
8bd0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
8be0: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
8bf0: 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62   for TEMP  datab
8c00: 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61  ases, journals a
8c10: 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61  nd for subjourna
8c20: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34  ls..**.** {H1114
8c30: 37 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  7} The [SQLITE_O
8c40: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
8c50: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
8c60: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
8c70: 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ned.** for exclu
8c80: 73 69 76 65 20 61 63 63 65 73 73 2e 20 20 54 68  sive access.  Th
8c90: 69 73 20 66 6c 61 67 20 69 73 20 73 65 74 20 66  is flag is set f
8ca0: 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20 65 78 63  or all files exc
8cb0: 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ept.** for the m
8cc0: 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
8cd0: 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 38  e..**.** {H11148
8ce0: 7d 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46  } At least szOsF
8cf0: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
8d00: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
8d10: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
8d20: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
8d30: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
8d40: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
8d50: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
8d60: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 7b  ment to xOpen. {
8d70: 45 4e 44 7d 20 20 54 68 65 20 78 4f 70 65 6e 20  END}  The xOpen 
8d80: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
8d90: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
8da0: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
8db0: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
8dc0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a  t fill it in..**
8dd0: 0a 2a 2a 20 7b 48 31 31 31 34 39 7d 20 54 68 65  .** {H11149} The
8de0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
8df0: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
8e00: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
8e10: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
8e20: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
8e30: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
8e40: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
8e50: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
8e60: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
8e70: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
8e80: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
8e90: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
8ea0: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
8eb0: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
8ec0: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
8ed0: 74 20 72 65 61 64 61 62 6c 65 2e 20 7b 45 4e 44  t readable. {END
8ee0: 7d 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20  }  The file can 
8ef0: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
8f00: 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 35 30  y..**.** {H11150
8f10: 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  } SQLite will al
8f20: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
8f30: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
8f40: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68  e+1 bytes for th
8f50: 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66  e.** output buff
8f60: 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  er xFullPathname
8f70: 2e 20 7b 48 31 31 31 35 31 7d 20 54 68 65 20 65  . {H11151} The e
8f80: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
8f90: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
8fa0: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
8fb0: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
8fc0: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
8fd0: 2e 20 7b 45 4e 44 7d 20 20 49 66 20 74 68 65 20  . {END}  If the 
8fe0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
8ff0: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
9000: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
9010: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
9020: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
9030: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
9040: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
9050: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
9060: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
9070: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
9080: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
9090: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
90a0: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
90b0: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
90c0: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
90d0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
90e0: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
90f0: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
9100: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
9110: 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c   are not strictl
9120: 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20  y a part of the 
9130: 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20  filesystem, but 
9140: 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c  they are.** incl
9150: 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20  uded in the VFS 
9160: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f  structure for co
9170: 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54  mpleteness..** T
9180: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
9190: 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70   function attemp
91a0: 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79  ts to return nBy
91b0: 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  tes bytes.** of 
91c0: 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e  good-quality ran
91d0: 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75  domness into zOu
91e0: 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  t.  The return v
91f0: 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61  alue is.** the a
9200: 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  ctual number of 
9210: 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
9220: 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a  ess obtained..**
9230: 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   The xSleep() me
9240: 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20  thod causes the 
9250: 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74  calling thread t
9260: 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a  o sleep for at.*
9270: 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62  * least the numb
9280: 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e  er of microsecon
9290: 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78  ds given.  The x
92a0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
92b0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
92c0: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
92d0: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
92e0: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
92f0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
9300: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
9310: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74   sqlite3_vfs;.st
9320: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
9330: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
9340: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
9350: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
9360: 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69  on number */.  i
9370: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
9380: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
9390: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
93a0: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
93b0: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
93c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
93d0: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
93e0: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
93f0: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
9400: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
9410: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
9420: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
9430: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
9440: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
9450: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
9460: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
9470: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
9480: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
9490: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
94a0: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
94b0: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
94c0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
94d0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
94e0: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
94f0: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
9500: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
9510: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
9520: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
9530: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
9540: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
9550: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
9560: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
9570: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
9580: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
9590: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
95a0: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
95b0: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
95c0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
95d0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
95e0: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
95f0: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
9600: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9610: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
9620: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
9630: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
9640: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
9650: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
9660: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
9670: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
9680: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
9690: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20  har *zSymbol);. 
96a0: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
96b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
96c0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
96d0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
96e0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
96f0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
9700: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
9710: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
9720: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
9730: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
9740: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
9750: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
9760: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
9770: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
9780: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
9790: 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69   *);.  /* New fi
97a0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
97b0: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
97c0: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
97d0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
97e0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
97f0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
9800: 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f  appens. */.};../
9810: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
9820: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
9830: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 20  cess VFS method 
9840: 7b 48 31 31 31 39 30 7d 20 3c 48 31 31 31 34 30  {H11190} <H11140
9850: 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 39 31 7d  >.**.** {H11191}
9860: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
9870: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
9880: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
9890: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
98a0: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
98b0: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
98c0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
98d0: 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65 74   {END}  They det
98e0: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
98f0: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
9900: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
9910: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
9920: 20 66 6f 72 2e 0a 2a 2a 20 7b 48 31 31 31 39 32   for..** {H11192
9930: 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  } With SQLITE_AC
9940: 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
9950: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
9960: 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
9970: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
9980: 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 7b 48 31  e exists..** {H1
9990: 31 31 39 33 7d 20 57 69 74 68 20 53 51 4c 49 54  1193} With SQLIT
99a0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
99b0: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
99c0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
99d0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
99e0: 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  e is both readab
99f0: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e  le and writable.
9a00: 0a 2a 2a 20 7b 48 31 31 31 39 34 7d 20 57 69 74  .** {H11194} Wit
9a10: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
9a20: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
9a30: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
9a40: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
9a50: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
9a60: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
9a70: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
9a80: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
9a90: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
9aa0: 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20  WRITE 1.#define 
9ab0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
9ac0: 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a  AD      2../*.**
9ad0: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
9ae0: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
9af0: 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33 30   Library {H10130
9b00: 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30  } <S20000><S3010
9b10: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
9b20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9b30: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
9b40: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
9b50: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
9b60: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
9b70: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
9b80: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
9b90: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
9ba0: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
9bb0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9bc0: 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  ize()..**.** A c
9bd0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
9be0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
9bf0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
9c00: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
9c10: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
9c20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9c30: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
9c40: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
9c50: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
9c60: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
9c70: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
9c80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9c90: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
9ca0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
9cb0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
9cc0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79  hutdown().  Only
9cd0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
9ce0: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
9cf0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
9d00: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
9d10: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
9d20: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
9d30: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a  armless no-ops..
9d40: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
9d50: 72 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 74 65  r things, sqlite
9d60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
9d70: 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  hall invoke.** s
9d80: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
9d90: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 73 71  .  Similarly, sq
9da0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9db0: 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65  .** shall invoke
9dc0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
9dd0: 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
9de0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9df0: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
9e00: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
9e10: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20   success..** If 
9e20: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
9e30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9e40: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
9e50: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
9e60: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
9e70: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
9e80: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
9e90: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
9ea0: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
9eb0: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
9ec0: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
9ed0: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
9ee0: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  TE_OK]..**.** Th
9ef0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9f00: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
9f10: 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
9f20: 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
9f30: 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
9f40: 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
9f50: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
9f60: 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
9f70: 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
9f80: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9f90: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
9fa0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
9fb0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
9fc0: 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
9fd0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
9fe0: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
9ff0: 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
a000: 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
a010: 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
a020: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
a030: 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
a040: 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
a050: 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
a060: 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51    However, if SQ
a070: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
a080: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
a090: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
a0a0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
a0b0: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
a0c0: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
a0d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
a0e0: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
a0f0: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
a100: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
a110: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
a120: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
a130: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
a140: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
a150: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
a160: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
a170: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
a180: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
a190: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
a1a0: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
a1b0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
a1c0: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
a1d0: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
a1e0: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
a1f0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
a200: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
a210: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
a220: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
a230: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
a240: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
a250: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
a260: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
a270: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
a280: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
a290: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
a2a0: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
a2b0: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
a2c0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
a2d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
a2e0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
a2f0: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
a300: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
a310: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
a320: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
a330: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
a340: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
a350: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
a360: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
a370: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
a380: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
a390: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
a3a0: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
a3b0: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
a3c0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
a3d0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
a3e0: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
a3f0: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
a400: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
a410: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
a420: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
a430: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
a440: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
a450: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
a460: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
a470: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
a480: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
a490: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
a4a0: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
a4b0: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
a4c0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
a4d0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
a4e0: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
a4f0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
a500: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
a510: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
a520: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
a530: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
a540: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
a550: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
a560: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
a570: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
a580: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a590: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
a5a0: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
a5b0: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
a5c0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
a5d0: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
a5e0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
a5f0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a600: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
a610: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
a620: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
a630: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
a640: 6c 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69  led for unix, wi
a650: 6e 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a  ndows, or os/2..
a660: 2a 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f  ** When built fo
a670: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
a680: 73 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51  s (using the [SQ
a690: 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d  LITE_OS_OTHER=1]
a6a0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
a6b0: 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70   option) the app
a6c0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
a6d0: 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20  pply a suitable 
a6e0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
a6f0: 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  or.** sqlite3_os
a700: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
a710: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41  te3_os_end().  A
a720: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  n application-su
a730: 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d  pplied.** implem
a740: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
a750: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72  te3_os_init() or
a760: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a770: 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e  ).** must return
a780: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
a790: 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65  success and some
a7a0: 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f   other [error co
a7b0: 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c  de] upon.** fail
a7c0: 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ure..*/.int sqli
a7d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76  te3_initialize(v
a7e0: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
a7f0: 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
a800: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
a810: 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74  _init(void);.int
a820: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a830: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
a840: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
a850: 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
a860: 69 62 72 61 72 79 20 7b 48 31 34 31 30 30 7d 20  ibrary {H14100} 
a870: 3c 53 32 30 30 30 30 3e 3c 53 33 30 32 30 30 3e  <S20000><S30200>
a880: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
a890: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
a8a0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
a8b0: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
a8c0: 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e   make global con
a8d0: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
a8e0: 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20  anges to SQLite 
a8f0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65  in order to tune
a900: 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73   SQLite to the s
a910: 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
a920: 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
a930: 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ion.  The defaul
a940: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
a950: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
a960: 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  or most.** appli
a970: 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74  cations and so t
a980: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
a990: 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73  sually not neces
a9a0: 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20  sary.  It is.** 
a9b0: 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70  provided to supp
a9c0: 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61  ort rare applica
a9d0: 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75  tions with unusu
a9e0: 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  al needs..**.** 
a9f0: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
aa00: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
aa10: 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
aa20: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
aa30: 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72  on.** must insur
aa40: 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20  e that no other 
aa50: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
aa60: 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79  s are invoked by
aa70: 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64   other.** thread
aa80: 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  s while sqlite3_
aa90: 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e  config() is runn
aaa0: 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72  ing.  Furthermor
aab0: 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e, sqlite3_confi
aac0: 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  g().** may only 
aad0: 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72  be invoked prior
aae0: 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74   to library init
aaf0: 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67  ialization using
ab00: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  .** [sqlite3_ini
ab10: 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  tialize()] or af
ab20: 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20  ter shutdown by 
ab30: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
ab40: 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  n()]..** Note, h
ab50: 6f 77 65 76 65 72 2c 20 74 68 61 74 20 73 71 6c  owever, that sql
ab60: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
ab70: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
ab80: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
ab90: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
aba0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
abb0: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
abc0: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
abd0: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
abe0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
abf0: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
ac00: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
ac10: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
ac20: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
ac30: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
ac40: 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
ac50: 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
ac60: 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
ac70: 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
ac80: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
ac90: 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
aca0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51  nding on the [SQ
acb0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
acc0: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
acd0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
ace0: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
acf0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
ad00: 20 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72   When a configur
ad10: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
ad20: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
ad30: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
ad40: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 49 66  QLITE_OK]..** If
ad50: 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
ad60: 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
ad70: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
ad80: 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
ad90: 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
ada0: 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
adb0: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
adc0: 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
add0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31  NTS:.**.** {H141
ade0: 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  03} A successful
adf0: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
ae00: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ae10: 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a  ] shall return.*
ae20: 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
ae30: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  TE_OK]..**.** {H
ae40: 31 34 31 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  14106} The [sqli
ae50: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
ae60: 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65  terface shall re
ae70: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
ae80: 55 53 45 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  USE].**         
ae90: 20 69 66 20 69 74 20 69 73 20 69 6e 76 6f 6b 65   if it is invoke
aea0: 64 20 69 6e 20 62 65 74 77 65 65 6e 20 63 61 6c  d in between cal
aeb0: 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69  ls to [sqlite3_i
aec0: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
aed0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
aee0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
aef0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 30  ]..**.** {H14120
af00: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
af10: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
af20: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
af30: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
af40: 45 41 44 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20  EAD]).**        
af50: 20 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20    shall set the 
af60: 64 65 66 61 75 6c 74 20 5b 74 68 72 65 61 64 69  default [threadi
af70: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67  ng mode] to Sing
af80: 6c 65 2d 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a  le-thread..**.**
af90: 20 7b 48 31 34 31 32 33 7d 20 41 20 73 75 63 63   {H14123} A succ
afa0: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
afb0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
afc0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
afd0: 55 4c 54 49 54 48 52 45 41 44 5d 29 0a 2a 2a 20  ULTITHREAD]).** 
afe0: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73           shall s
aff0: 65 74 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  et the default [
b000: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
b010: 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
b020: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 36 7d 20  .**.** {H14126} 
b030: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
b040: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
b050: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
b060: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
b070: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ).**          sh
b080: 61 6c 6c 20 73 65 74 20 74 68 65 20 64 65 66 61  all set the defa
b090: 75 6c 74 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ult [threading m
b0a0: 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
b0b0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32  ed..**.** {H1412
b0c0: 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  9} A successful 
b0d0: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
b0e0: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
b0f0: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2c 58  _CONFIG_MUTEX],X
b100: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  ).**          wh
b110: 65 72 65 20 58 20 69 73 20 61 20 70 6f 69 6e 74  ere X is a point
b120: 65 72 20 74 6f 20 61 6e 20 69 6e 69 74 69 61 6c  er to an initial
b130: 69 7a 65 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ized [sqlite3_mu
b140: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
b150: 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20           object 
b160: 73 68 61 6c 6c 20 63 61 75 73 65 20 61 6c 6c 20  shall cause all 
b170: 73 75 62 73 65 71 75 65 6e 74 20 6d 75 74 65 78  subsequent mutex
b180: 20 6f 70 65 72 61 74 69 6f 6e 73 20 70 65 72 66   operations perf
b190: 6f 72 6d 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  ormed.**        
b1a0: 20 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 75    by SQLite to u
b1b0: 73 65 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74  se the mutex met
b1c0: 68 6f 64 73 20 74 68 61 74 20 77 65 72 65 20 70  hods that were p
b1d0: 72 65 73 65 6e 74 20 69 6e 20 58 0a 2a 2a 20 20  resent in X.**  
b1e0: 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 74          during t
b1f0: 68 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  he call to [sqli
b200: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
b210: 2a 0a 2a 2a 20 7b 48 31 34 31 33 32 7d 20 41 20  *.** {H14132} A 
b220: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
b230: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
b240: 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
b250: 49 47 5f 47 45 54 4d 55 54 45 58 5d 2c 58 29 0a  IG_GETMUTEX],X).
b260: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72  **          wher
b270: 65 20 58 20 69 73 20 61 20 70 6f 69 6e 74 65 72  e X is a pointer
b280: 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
b290: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 6f  mutex_methods] o
b2a0: 62 6a 65 63 74 20 0a 2a 2a 20 20 20 20 20 20 20  bject .**       
b2b0: 20 20 20 73 68 61 6c 6c 20 6f 76 65 72 77 72 69     shall overwri
b2c0: 74 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  te the content o
b2d0: 66 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  f [sqlite3_mutex
b2e0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
b2f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
b300: 68 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68  h the mutex meth
b310: 6f 64 73 20 63 75 72 72 65 6e 74 6c 79 20 69 6e  ods currently in
b320: 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 2e 0a   use by SQLite..
b330: 2a 2a 0a 2a 2a 20 7b 48 31 34 31 33 35 7d 20 41  **.** {H14135} A
b340: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
b350: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
b360: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
b370: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2c 4d 29 0a 2a  FIG_MALLOC],M).*
b380: 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65  *          where
b390: 20 4d 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20   M is a pointer 
b3a0: 74 6f 20 61 6e 20 69 6e 69 74 69 61 6c 69 7a 65  to an initialize
b3b0: 64 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  d [sqlite3_mem_m
b3c0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 20 20 20 20 20  ethods].**      
b3d0: 20 20 20 20 6f 62 6a 65 63 74 20 73 68 61 6c 6c      object shall
b3e0: 20 63 61 75 73 65 20 61 6c 6c 20 73 75 62 73 65   cause all subse
b3f0: 71 75 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  quent memory all
b400: 6f 63 61 74 69 6f 6e 20 6f 70 65 72 61 74 69 6f  ocation operatio
b410: 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  ns.**          p
b420: 65 72 66 6f 72 6d 65 64 20 62 79 20 53 51 4c 69  erformed by SQLi
b430: 74 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65  te to use the me
b440: 74 68 6f 64 73 20 74 68 61 74 20 77 65 72 65 20  thods that were 
b450: 70 72 65 73 65 6e 74 20 69 6e 20 0a 2a 2a 20 20  present in .**  
b460: 20 20 20 20 20 20 20 20 4d 20 64 75 72 69 6e 67          M during
b470: 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71   the call to [sq
b480: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
b490: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 33 38 7d 20  .**.** {H14138} 
b4a0: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
b4b0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
b4c0: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
b4d0: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2c  NFIG_GETMALLOC],
b4e0: 4d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  M).**          w
b4f0: 68 65 72 65 20 4d 20 69 73 20 61 20 70 6f 69 6e  here M is a poin
b500: 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74  ter to an [sqlit
b510: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
b520: 6f 62 6a 65 63 74 20 73 68 61 6c 6c 0a 2a 2a 20  object shall.** 
b530: 20 20 20 20 20 20 20 20 20 6f 76 65 72 77 72 69           overwri
b540: 74 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  te the content o
b550: 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  f [sqlite3_mem_m
b560: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 77  ethods] object w
b570: 69 74 68 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ith .**         
b580: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
b590: 63 61 74 69 6f 6e 20 6d 65 74 68 6f 64 73 20 63  cation methods c
b5a0: 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 20  urrently in use 
b5b0: 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  by.**          S
b5c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  QLite..**.** {H1
b5d0: 34 31 34 31 7d 20 41 20 73 75 63 63 65 73 73 66  4141} A successf
b5e0: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
b5f0: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
b600: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
b610: 41 54 55 53 5d 2c 31 29 0a 2a 2a 20 20 20 20 20  ATUS],1).**     
b620: 20 20 20 20 20 73 68 61 6c 6c 20 65 6e 61 62 6c       shall enabl
b630: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
b640: 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73 20 63  ocation status c
b650: 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 63 2e  ollection logic.
b660: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34 34 7d 20  .**.** {H14144} 
b670: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
b680: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
b690: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
b6a0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c  NFIG_MEMSTATUS],
b6b0: 30 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  0).**          s
b6c0: 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65  hall disable the
b6d0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
b6e0: 6f 6e 20 73 74 61 74 75 73 20 63 6f 6c 6c 65 63  on status collec
b6f0: 74 69 6f 6e 20 6c 6f 67 69 63 2e 0a 2a 2a 0a 2a  tion logic..**.*
b700: 2a 20 7b 48 31 34 31 34 37 7d 20 54 68 65 20 6d  * {H14147} The m
b710: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b720: 20 73 74 61 74 75 73 20 63 6f 6c 6c 65 63 74 69   status collecti
b730: 6f 6e 20 6c 6f 67 69 63 20 73 68 61 6c 6c 20 62  on logic shall b
b740: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e  e.**          en
b750: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
b760: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35 30 7d  ..**.** {H14150}
b770: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
b780: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
b790: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
b7a0: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 2c 53  ONFIG_SCRATCH],S
b7b0: 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20  ,Z,N).**        
b7c0: 20 20 77 68 65 72 65 20 5a 20 61 6e 64 20 4e 20    where Z and N 
b7d0: 61 72 65 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  are non-negative
b7e0: 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20 0a 2a   integers and .*
b7f0: 2a 20 20 20 20 20 20 20 20 20 20 53 20 69 73 20  *          S is 
b800: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
b810: 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
b820: 75 66 66 65 72 20 6e 6f 74 20 6c 65 73 73 20 74  uffer not less t
b830: 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  han.**          
b840: 5a 2a 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  Z*N bytes in siz
b850: 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20 53 20  e shall cause S 
b860: 74 6f 20 62 65 20 75 73 65 64 20 62 79 20 74 68  to be used by th
b870: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
b880: 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c  cratch memory al
b890: 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 61 73 20  locator] for as 
b8a0: 6d 61 6e 79 20 61 73 20 4e 20 73 69 6d 75 6c 61  many as N simula
b8b0: 74 61 6e 65 6f 75 73 0a 2a 2a 20 20 20 20 20 20  taneous.**      
b8c0: 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20      allocations 
b8d0: 65 61 63 68 20 6f 66 20 73 69 7a 65 20 5a 2e 0a  each of size Z..
b8e0: 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35 33 7d 20 41  **.** {H14153} A
b8f0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
b900: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
b910: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
b920: 46 49 47 5f 53 43 52 41 54 43 48 5d 2c 53 2c 5a  FIG_SCRATCH],S,Z
b930: 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ,N).**          
b940: 77 68 65 72 65 20 53 20 69 73 20 61 20 4e 55 4c  where S is a NUL
b950: 4c 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20  L pointer shall 
b960: 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 20  disable the.**  
b970: 20 20 20 20 20 20 20 20 5b 73 63 72 61 74 63 68          [scratch
b980: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
b990: 72 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35  r]..**.** {H1415
b9a0: 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  6} A successful 
b9b0: 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20  call to.**      
b9c0: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e      [sqlite3_con
b9d0: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
b9e0: 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 53  FIG_PAGECACHE],S
b9f0: 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20  ,Z,N).**        
ba00: 20 20 77 68 65 72 65 20 5a 20 61 6e 64 20 4e 20    where Z and N 
ba10: 61 72 65 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  are non-negative
ba20: 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20 0a 2a   integers and .*
ba30: 2a 20 20 20 20 20 20 20 20 20 20 53 20 69 73 20  *          S is 
ba40: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
ba50: 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
ba60: 75 66 66 65 72 20 6e 6f 74 20 6c 65 73 73 20 74  uffer not less t
ba70: 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  han.**          
ba80: 5a 2a 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  Z*N bytes in siz
ba90: 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20 53 20  e shall cause S 
baa0: 74 6f 20 62 65 20 75 73 65 64 20 62 79 20 74 68  to be used by th
bab0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
bac0: 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  agecache memory 
bad0: 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 61  allocator] for a
bae0: 73 20 6d 61 6e 79 20 61 73 20 4e 20 73 69 6d 75  s many as N simu
baf0: 6c 61 74 61 6e 65 6f 75 73 0a 2a 2a 20 20 20 20  lataneous.**    
bb00: 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e        allocation
bb10: 73 20 65 61 63 68 20 6f 66 20 73 69 7a 65 20 5a  s each of size Z
bb20: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35 39 7d  ..**.** {H14159}
bb30: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
bb40: 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ll to.**        
bb50: 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69    [sqlite3_confi
bb60: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
bb70: 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 53 2c 5a  G_PAGECACHE],S,Z
bb80: 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ,N).**          
bb90: 77 68 65 72 65 20 53 20 69 73 20 61 20 4e 55 4c  where S is a NUL
bba0: 4c 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20  L pointer shall 
bbb0: 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 20  disable the.**  
bbc0: 20 20 20 20 20 20 20 20 5b 70 61 67 65 63 61 63          [pagecac
bbd0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
bbe0: 74 6f 72 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34  tor]..**.** {H14
bbf0: 31 36 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  162} A successfu
bc00: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
bc10: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
bc20: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 2c  TE_CONFIG_HEAP],
bc30: 48 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20  H,Z,N).**       
bc40: 20 20 20 77 68 65 72 65 20 5a 20 61 6e 64 20 4e     where Z and N
bc50: 20 61 72 65 20 6e 6f 6e 2d 6e 65 67 61 74 69 76   are non-negativ
bc60: 65 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20 0a  e integers and .
bc70: 2a 2a 20 20 20 20 20 20 20 20 20 20 48 20 69 73  **          H is
bc80: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
bc90: 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
bca0: 62 75 66 66 65 72 20 6e 6f 74 20 6c 65 73 73 20  buffer not less 
bcb0: 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
bcc0: 20 5a 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   Z bytes in size
bcd0: 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 20 74 68   shall enable th
bce0: 65 20 5b 6d 65 6d 73 79 73 35 5d 20 6d 65 6d 6f  e [memsys5] memo
bcf0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 0a 2a 2a 20  ry allocator.** 
bd00: 20 20 20 20 20 20 20 20 20 61 6e 64 20 63 61 75           and cau
bd10: 73 65 20 69 74 20 74 6f 20 75 73 65 20 62 75 66  se it to use buf
bd20: 66 65 72 20 53 20 61 73 20 69 74 73 20 6d 65 6d  fer S as its mem
bd30: 6f 72 79 20 73 6f 75 72 63 65 20 61 6e 64 20 74  ory source and t
bd40: 6f 20 75 73 65 0a 2a 2a 20 20 20 20 20 20 20 20  o use.**        
bd50: 20 20 61 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f    a minimum allo
bd60: 63 61 74 69 6f 6e 20 73 69 7a 65 20 6f 66 20 4e  cation size of N
bd70: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 36 35 7d  ..**.** {H14165}
bd80: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
bd90: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
bda0: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
bdb0: 4f 4e 46 49 47 5f 48 45 41 50 5d 2c 48 2c 5a 2c  ONFIG_HEAP],H,Z,
bdc0: 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  N).**          w
bdd0: 68 65 72 65 20 48 20 69 73 20 61 20 4e 55 4c 4c  here H is a NULL
bde0: 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 64   pointer shall d
bdf0: 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 20 20  isable the.**   
be00: 20 20 20 20 20 20 20 5b 6d 65 6d 73 79 73 35 5d         [memsys5]
be10: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
be20: 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 36 38  r..**.** {H14168
be30: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
be40: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
be50: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
be60: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
be70: 5d 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20  ],Z,N).**       
be80: 20 20 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74     shall cause t
be90: 68 65 20 64 65 66 61 75 6c 74 20 5b 6c 6f 6f 6b  he default [look
bea0: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
beb0: 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
bec0: 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ation.**        
bed0: 20 20 66 6f 72 20 6e 65 77 20 5b 64 61 74 61 62    for new [datab
bee0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
bef0: 20 74 6f 20 62 65 20 4e 20 73 6c 6f 74 73 20 6f   to be N slots o
bf00: 66 20 5a 20 62 79 74 65 73 20 65 61 63 68 2e 0a  f Z bytes each..
bf10: 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
bf20: 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
bf30: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
bf40: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
bf50: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
bf60: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
bf70: 69 6f 6e 73 20 20 7b 48 31 34 32 30 30 7d 20 3c  ions  {H14200} <
bf80: 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S20000>.** EXPER
bf90: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
bfa0: 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
bfb0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
bfc0: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
bfd0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
bfe0: 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
bff0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
c000: 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
c010: 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
c020: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
c030: 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
c040: 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
c050: 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
c060: 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
c070: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
c080: 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
c090: 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 54  st argument).  T
c0a0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62  he.** sqlite3_db
c0b0: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
c0c0: 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ace can only be 
c0d0: 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  used immediately
c0e0: 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61   after.** the da
c0f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c100: 6e 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69  n is created usi
c110: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ng [sqlite3_open
c120: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
c130: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b  _open16()], or [
c140: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
c150: 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  )].  .**.** The 
c160: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
c170: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
c180: 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69  nfig(D,V,...)  i
c190: 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  s the.** configu
c1a0: 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e  ration verb - an
c1b0: 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
c1c0: 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
c1d0: 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74  t.** aspect of t
c1e0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
c1f0: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
c200: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
c210: 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65   The only choice
c220: 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20   for this value 
c230: 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  is [SQLITE_DBCON
c240: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a  FIG_LOOKASIDE]..
c250: 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72 65  ** New verbs are
c260: 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64   likely to be ad
c270: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
c280: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
c290: 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
c2a0: 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64  arguments depend
c2b0: 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a   on the verb..**
c2c0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
c2d0: 2a 2a 0a 2a 2a 20 7b 48 31 34 32 30 33 7d 20 41  **.** {H14203} A
c2e0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
c2f0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c  3_db_config(D,V,
c300: 2e 2e 2e 29 5d 20 73 68 61 6c 6c 20 72 65 74 75  ...)] shall retu
c310: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a  rn [SQLITE_OK].*
c320: 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 61 6e  *          if an
c330: 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 63 61  d only if the ca
c340: 6c 6c 20 69 73 20 73 75 63 63 65 73 73 66 75 6c  ll is successful
c350: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 30 36 7d  ..**.** {H14206}
c360: 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   If one or more 
c370: 73 6c 6f 74 73 20 6f 66 20 74 68 65 20 5b 6c 6f  slots of the [lo
c380: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
c390: 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 0a 2a 2a  llocator] for.**
c3a0: 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
c3b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
c3c0: 44 20 61 72 65 20 69 6e 20 75 73 65 2c 20 74 68  D are in use, th
c3d0: 65 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  en a call to.** 
c3e0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
c3f0: 33 5f 64 62 5f 63 6f 6e 66 69 67 5d 28 44 2c 5b  3_db_config](D,[
c400: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
c410: 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
c420: 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  shall.**        
c430: 20 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 5b    fail with an [
c440: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 72 65 74  SQLITE_BUSY] ret
c450: 75 72 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  urn code..**.** 
c460: 7b 48 31 34 32 30 39 7d 20 41 20 73 75 63 63 65  {H14209} A succe
c470: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a  ssful call to .*
c480: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
c490: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 5d 28 44  te3_db_config](D
c4a0: 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  ,[SQLITE_DBCONFI
c4b0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 42 2c 5a  G_LOOKASIDE],B,Z
c4c0: 2c 4e 29 20 77 68 65 72 65 0a 2a 2a 20 20 20 20  ,N) where.**    
c4d0: 20 20 20 20 20 20 44 20 69 73 20 61 6e 20 6f 70        D is an op
c4e0: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
c4f0: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5a 20 61  nection] and Z a
c500: 6e 64 20 4e 20 61 72 65 20 70 6f 73 69 74 69 76  nd N are positiv
c510: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
c520: 74 65 67 65 72 73 20 61 6e 64 20 42 20 69 73 20  tegers and B is 
c530: 61 6e 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  an aligned buffe
c540: 72 20 61 74 20 6c 65 61 73 74 20 5a 2a 4e 20 62  r at least Z*N b
c550: 79 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20  ytes in size.** 
c560: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 63           shall c
c570: 61 75 73 65 20 74 68 65 20 5b 6c 6f 6f 6b 61 73  ause the [lookas
c580: 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
c590: 61 74 6f 72 5d 20 66 6f 72 20 44 20 74 6f 20 75  ator] for D to u
c5a0: 73 65 20 62 75 66 66 65 72 20 42 20 0a 2a 2a 20  se buffer B .** 
c5b0: 20 20 20 20 20 20 20 20 20 77 69 74 68 20 4e 20           with N 
c5c0: 73 6c 6f 74 73 20 6f 66 20 5a 20 62 79 74 65 73  slots of Z bytes
c5d0: 20 65 61 63 68 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   each..**.** {H1
c5e0: 34 32 31 32 7d 20 41 20 73 75 63 63 65 73 73 66  4212} A successf
c5f0: 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 20  ul call to .**  
c600: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
c610: 5f 64 62 5f 63 6f 6e 66 69 67 5d 28 44 2c 5b 53  _db_config](D,[S
c620: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
c630: 4f 4f 4b 41 53 49 44 45 5d 2c 42 2c 5a 2c 4e 29  OOKASIDE],B,Z,N)
c640: 20 77 68 65 72 65 0a 2a 2a 20 20 20 20 20 20 20   where.**       
c650: 20 20 20 44 20 69 73 20 61 6e 20 6f 70 65 6e 20     D is an open 
c660: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c670: 74 69 6f 6e 5d 20 61 6e 64 20 5a 20 61 6e 64 20  tion] and Z and 
c680: 4e 20 61 72 65 20 70 6f 73 69 74 69 76 65 0a 2a  N are positive.*
c690: 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 67  *          integ
c6a0: 65 72 73 20 61 6e 64 20 42 20 69 73 20 4e 55 4c  ers and B is NUL
c6b0: 4c 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20  L pointer shall 
c6c0: 63 61 75 73 65 20 74 68 65 0a 2a 2a 20 20 20 20  cause the.**    
c6d0: 20 20 20 20 20 20 5b 6c 6f 6f 6b 61 73 69 64 65        [lookaside
c6e0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
c6f0: 72 5d 20 66 6f 72 20 44 20 74 6f 20 61 20 6f 62  r] for D to a ob
c700: 74 61 69 6e 20 5a 2a 4e 20 62 79 74 65 20 62 75  tain Z*N byte bu
c710: 66 66 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ffer.**         
c720: 20 66 72 6f 6d 20 74 68 65 20 70 72 69 6d 61 72   from the primar
c730: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
c740: 6f 72 20 61 6e 64 20 75 73 65 20 74 68 61 74 20  or and use that 
c750: 62 75 66 66 65 72 0a 2a 2a 20 20 20 20 20 20 20  buffer.**       
c760: 20 20 20 77 69 74 68 20 4e 20 6c 6f 6f 6b 61 73     with N lookas
c770: 69 64 65 20 73 6c 6f 74 73 20 6f 66 20 5a 20 62  ide slots of Z b
c780: 79 74 65 73 20 65 61 63 68 2e 0a 2a 2a 0a 2a 2a  ytes each..**.**
c790: 20 7b 48 31 34 32 31 35 7d 20 41 20 73 75 63 63   {H14215} A succ
c7a0: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a  essful call to .
c7b0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
c7c0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 5d 28  ite3_db_config](
c7d0: 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  D,[SQLITE_DBCONF
c7e0: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 42 2c  IG_LOOKASIDE],B,
c7f0: 5a 2c 4e 29 20 77 68 65 72 65 0a 2a 2a 20 20 20  Z,N) where.**   
c800: 20 20 20 20 20 20 20 44 20 69 73 20 61 6e 20 6f         D is an o
c810: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
c820: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5a 20  nnection] and Z 
c830: 61 6e 64 20 4e 20 61 72 65 20 7a 65 72 6f 20 73  and N are zero s
c840: 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
c850: 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 6c 6f   disable the [lo
c860: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
c870: 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44 2e  llocator] for D.
c880: 0a 2a 2a 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45  .**.**.*/.SQLITE
c890: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e  _EXPERIMENTAL in
c8a0: 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  t sqlite3_db_con
c8b0: 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  fig(sqlite3*, in
c8c0: 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  t op, ...);../*.
c8d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
c8e0: 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52  ory Allocation R
c8f0: 6f 75 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d  outines {H10155}
c900: 20 3c 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50   <S20120>.** EXP
c910: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
c920: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
c930: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
c940: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
c950: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
c960: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
c970: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c980: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
c990: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
c9a0: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
c9b0: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
c9c0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
c9d0: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
c9e0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
c9f0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
ca00: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
ca10: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
ca20: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
ca30: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ca40: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
ca50: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
ca60: 2e 20 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  .  By creating a
ca70: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
ca80: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
ca90: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
caa0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
cab0: 5d 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  ] during configu
cac0: 72 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70  ration, an.** ap
cad0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
cae0: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
caf0: 74 69 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  tive memory allo
cb00: 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
cb10: 0a 2a 2a 20 66 6f 72 20 53 51 4c 69 74 65 20 74  .** for SQLite t
cb20: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
cb30: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
cb40: 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
cb50: 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
cb60: 65 20 63 6f 6d 65 73 20 77 69 74 68 20 61 20 62  e comes with a b
cb70: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
cb80: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 69 73  llocator that is
cb90: 0a 2a 2a 20 70 65 72 66 65 63 74 6c 79 20 61 64  .** perfectly ad
cba0: 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
cbb0: 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
cbc0: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
cbd0: 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
cbe0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
cbf0: 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
cc00: 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
cc10: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
cc20: 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
cc30: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
cc40: 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
cc50: 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
cc60: 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
cc70: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
cc80: 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
cc90: 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
cca0: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
ccb0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
ccc0: 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
ccd0: 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
cce0: 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
ccf0: 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
cd00: 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
cd10: 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
cd20: 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
cd30: 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
cd40: 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c  .** The xMalloc,
cd50: 20 78 46 72 65 65 2c 20 61 6e 64 20 78 52 65 61   xFree, and xRea
cd60: 6c 6c 6f 63 20 6d 65 74 68 6f 64 73 20 6d 75 73  lloc methods mus
cd70: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
cd80: 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65  ** malloc(), fre
cd90: 65 28 29 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63  e(), and realloc
cda0: 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
cdb0: 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c  m the standard l
cdc0: 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53  ibrary..**.** xS
cdd0: 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
cde0: 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
cdf0: 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
ce00: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
ce10: 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
ce20: 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
ce30: 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
ce40: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
ce50: 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
ce60: 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
ce70: 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
ce80: 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
ce90: 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
cea0: 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
ceb0: 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
cec0: 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
ced0: 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
cee0: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
cef0: 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
cf00: 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
cf10: 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
cf20: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
cf30: 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
cf40: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
cf50: 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
cf60: 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
cf70: 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
cf80: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
cf90: 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
cfa0: 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
cfb0: 72 20 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68  r of 2..**.** Th
cfc0: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
cfd0: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
cfe0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
cff0: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a    (For example,.
d000: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
d010: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
d020: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
d030: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
d040: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
d050: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
d060: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
d070: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
d080: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
d090: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
d0a0: 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
d0b0: 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
d0c0: 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
d0d0: 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
d0e0: 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
d0f0: 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
d100: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
d110: 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
d120: 64 6f 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  down..*/.typedef
d130: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
d140: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
d150: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
d160: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
d170: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
d180: 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
d190: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
d1a0: 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
d1b0: 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
d1c0: 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
d1d0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
d1e0: 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
d1f0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
d200: 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
d210: 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
d220: 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
d230: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
d240: 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
d250: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
d260: 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
d270: 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
d280: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
d290: 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
d2a0: 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
d2b0: 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
d2c0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
d2d0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
d2e0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
d2f0: 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
d300: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
d310: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
d320: 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
d330: 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
d340: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
d350: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
d360: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
d370: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
d380: 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
d390: 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
d3a0: 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
d3b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d3c0: 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
d3d0: 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d  Options {H10160}
d3e0: 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50   <S20000>.** EXP
d3f0: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
d400: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
d410: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
d420: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
d430: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
d440: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
d450: 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
d460: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
d470: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
d480: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
d490: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
d4a0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
d4b0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
d4c0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
d4d0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
d4e0: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
d4f0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
d500: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
d510: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
d520: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
d530: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
d540: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
d550: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
d560: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
d570: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
d580: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
d590: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
d5a0: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
d5b0: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
d5c0: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
d5d0: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
d5e0: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
d5f0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
d600: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
d610: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
d620: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
d630: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
d640: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
d650: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
d660: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
d670: 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61  This option disa
d680: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
d690: 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
d6a0: 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
d6b0: 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
d6c0: 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
d6d0: 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
d6e0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
d6f0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
d700: 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
d710: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
d720: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
d730: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54   this option.  T
d740: 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62  his option disab
d750: 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
d760: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
d770: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
d780: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
d790: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
d7a0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
d7b0: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
d7c0: 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
d7d0: 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
d7e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
d7f0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
d800: 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
d810: 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
d820: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
d830: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
d840: 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
d850: 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
d860: 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
d870: 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
d880: 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
d890: 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
d8a0: 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
d8b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
d8c0: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
d8d0: 20 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61    See the [threa
d8e0: 64 69 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 6f  ding mode].** do
d8f0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
d900: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
d910: 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  mation.</dd>.**.
d920: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
d930: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
d940: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
d950: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
d960: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
d970: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
d980: 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
d990: 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
d9a0: 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
d9b0: 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
d9c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d9d0: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
d9e0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
d9f0: 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
da00: 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
da10: 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
da20: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
da30: 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
da40: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
da50: 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
da60: 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
da70: 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
da80: 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
da90: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
daa0: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
dab0: 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
dac0: 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
dad0: 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
dae0: 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
daf0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
db00: 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
db10: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
db20: 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
db30: 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
db40: 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
db50: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  See the [threadi
db60: 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e  ng mode] documen
db70: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
db80: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
db90: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
dba0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
dbb0: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
dbc0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
dbd0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
dbe0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
dbf0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
dc00: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
dc10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
dc20: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
dc30: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
dc40: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
dc50: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
dc60: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
dc70: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
dc80: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
dc90: 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
dca0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
dcb0: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
dcc0: 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  nto SQLite.</dd>
dcd0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
dce0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
dcf0: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OC</dt>.** <dd>T
dd00: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
dd10: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
dd20: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
dd30: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
dd40: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
dd50: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
dd60: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
dd70: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
dd80: 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
dd90: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
dda0: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
ddb0: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
ddc0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
ddd0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73  outines..** This
dde0: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
ddf0: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
de00: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
de10: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
de20: 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
de30: 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
de40: 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
de50: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
de60: 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
de70: 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
de80: 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e  or example.</dd>
de90: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
dea0: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
deb0: 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  US</dt>.** <dd>T
dec0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
ded0: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
dee0: 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e   of type int, in
def0: 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a  terpreted as a .
df00: 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63  ** boolean, whic
df10: 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
df20: 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
df30: 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61  tion of memory a
df40: 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74  llocation .** st
df50: 61 74 69 73 74 69 63 73 2e 20 57 68 65 6e 20 64  atistics. When d
df60: 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c  isabled, the fol
df70: 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
df80: 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
df90: 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  .** non-operatio
dfa0: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
dfb0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
dfc0: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
dfd0: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
dfe0: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
dff0: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
e000: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
e010: 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  heap_limit()].**
e020: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
e030: 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20  _status()].**   
e040: 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  </ul>.** </dd>.*
e050: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e060: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
e070: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
e080: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
e090: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
e0a0: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
e0b0: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
e0c0: 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
e0d0: 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68  y.  There are th
e0e0: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20  ree arguments:  
e0f0: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
e100: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20   memory, the.** 
e110: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
e120: 61 74 63 68 20 62 75 66 66 65 72 20 28 73 7a 29  atch buffer (sz)
e130: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
e140: 20 6f 66 20 62 75 66 66 65 72 73 20 28 4e 29 2e   of buffers (N).
e150: 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
e160: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
e170: 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54  ultiple of 16. T
e180: 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20  he sz parameter 
e190: 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20  should be a few 
e1a0: 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20  bytes.** larger 
e1b0: 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20  than the actual 
e1c0: 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65  scratch space re
e1d0: 71 75 69 72 65 64 20 64 75 65 20 69 6e 74 65 72  quired due inter
e1e0: 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a  nal overhead..**
e1f0: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
e200: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
e210: 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
e220: 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
e230: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
e240: 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65  emory..** SQLite
e250: 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
e260: 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
e270: 63 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e 63  ch buffer at onc
e280: 65 20 70 65 72 20 74 68 72 65 61 64 2c 20 73 6f  e per thread, so
e290: 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20  .** N should be 
e2a0: 73 65 74 20 74 6f 20 74 68 65 20 65 78 70 65 63  set to the expec
e2b0: 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ted maximum numb
e2c0: 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20  er of threads.  
e2d0: 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65  The sz.** parame
e2e0: 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36 20  ter should be 6 
e2f0: 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20 6f  times the size o
e300: 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
e310: 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
e320: 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75 66  ..** Scratch buf
e330: 66 65 72 73 20 61 72 65 20 75 73 65 64 20 61 73  fers are used as
e340: 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 74 72   part of the btr
e350: 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 61  ee balance opera
e360: 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65  tion.  If.** The
e370: 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72 20   btree balancer 
e380: 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
e390: 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
e3a0: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
e3b0: 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 75  by.** scratch bu
e3c0: 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 73  ffers or if no s
e3d0: 63 72 61 74 63 68 20 62 75 66 66 65 72 20 73 70  cratch buffer sp
e3e0: 61 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64  ace is specified
e3f0: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
e400: 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
e410: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f  3_malloc()] to o
e420: 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
e430: 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a   it needs.</dd>.
e440: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
e450: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
e460: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  E</dt>.** <dd>Th
e470: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
e480: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
e490: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
e4a0: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
e4b0: 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
e4c0: 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
e4d0: 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
e4e0: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
e4f0: 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  enation.  .** Th
e500: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
e510: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
e520: 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
e530: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
e540: 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
e550: 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
e560: 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
e570: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
e580: 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  HE option..** Th
e590: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
e5a0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
e5b0: 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
e5c0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f  r to the.** memo
e5d0: 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
e5e0: 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
e5f0: 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
e600: 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
e610: 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
e620: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
e630: 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
e640: 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
e650: 37 36 38 2e 20 20 54 68 65 20 66 69 72 73 74 0a  768.  The first.
e660: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
e670: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
e680: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
e690: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
e6a0: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   of memory..** S
e6b0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
e6c0: 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
e6d0: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
e6e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
e6f0: 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
e700: 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
e710: 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
e720: 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
e730: 63 68 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f  che.  If additio
e740: 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
e750: 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
e760: 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
e770: 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
e780: 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
e790: 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
e7a0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
e7b0: 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
e7c0: 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
e7d0: 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d  space..** The im
e7e0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
e7f0: 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f  ht use one or mo
e800: 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66  re of the N buff
e810: 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20  ers to hold .** 
e820: 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e  memory accountin
e830: 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 3c  g information. <
e840: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e850: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
e860: 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
e870: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
e880: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
e890: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
e8a0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
e8b0: 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
e8c0: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
e8d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
e8e0: 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
e8f0: 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
e900: 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
e910: 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
e920: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
e930: 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
e940: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
e950: 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65 72  ments: A pointer
e960: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20   to the memory, 
e970: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
e980: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
e990: 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
e9a0: 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
e9b0: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20 49  ocation size.  I
e9c0: 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  f.** the first p
e9d0: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
e9e0: 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
e9f0: 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
ea00: 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
ea10: 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
ea20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
ea30: 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
ea40: 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
ea50: 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
ea60: 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
ea70: 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
ea80: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
ea90: 5d 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65  ].  If the.** me
eaa0: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
eab0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74  not NULL and eit
eac0: 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
ead0: 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a  LE_MEMSYS3] or.*
eae0: 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
eaf0: 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65  _MEMSYS5] are de
eb00: 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20  fined, then the 
eb10: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
eb20: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
eb30: 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
eb40: 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
eb50: 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
eb60: 61 74 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f 64 64  ation needs.</dd
eb70: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
eb80: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
eb90: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
eba0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
ebb0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
ebc0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
ebd0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
ebe0: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
ebf0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
ec00: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
ec10: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
ec20: 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
ec30: 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
ec40: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
ec50: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
ec60: 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
ec70: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
ec80: 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  nto SQLite.</dd>
ec90: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
eca0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
ecb0: 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  X</dt>.** <dd>Th
ecc0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
ecd0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
ece0: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
ecf0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
ed00: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
ed10: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
ed20: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
ed30: 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
ed40: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
ed50: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
ed60: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
ed70: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
ed80: 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
ed90: 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  s..** This optio
eda0: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
edb0: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
edc0: 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
edd0: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
ede0: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
edf0: 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
ee00: 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
ee10: 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
ee20: 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
ee30: 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
ee40: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ee50: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
ee60: 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
ee70: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
ee80: 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
ee90: 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
eea0: 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a  ine the default.
eeb0: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 63 61 74  ** memory allcat
eec0: 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20 6f 70  ion lookaside op
eed0: 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54 68 65  timization.  The
eee0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
eef0: 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
ef00: 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
ef10: 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
ef20: 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
ef30: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
ef40: 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
ef50: 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
ef60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f 64 64   connection.</dd
ef70: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
ef80: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
ef90: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
efa0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
efb0: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
efc0: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
efd0: 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71  ter to.** an [sq
efe0: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
eff0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  hods] object.  T
f000: 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
f010: 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  fies the interfa
f020: 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f  ce.** to a custo
f030: 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
f040: 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53 51  lementation.  SQ
f050: 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
f060: 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65  y of the.** obje
f070: 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66  ct and uses it f
f080: 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  or page cache me
f090: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
f0a0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
f0b0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
f0c0: 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  ETPCACHE</dt>.**
f0d0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
f0e0: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
f0f0: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
f100: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
f110: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
f120: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
f130: 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
f140: 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
f150: 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
f160: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
f170: 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
f180: 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  t.</dd>.**.** </
f190: 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
f1a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
f1b0: 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
f1c0: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
f1d0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
f1e0: 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
f1f0: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
f200: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
f210: 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
f220: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
f230: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f240: 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
f250: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
f260: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
f270: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
f280: 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
f290: 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
f2a0: 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
f2b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f2c0: 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
f2d0: 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
f2e0: 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
f2f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f300: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
f310: 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
f320: 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
f330: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f340: 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
f350: 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
f360: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
f370: 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
f380: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
f390: 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
f3a0: 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
f3b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f3c0: 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
f3d0: 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
f3e0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
f3f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f400: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
f410: 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
f420: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
f430: 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
f440: 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
f450: 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
f460: 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
f470: 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
f480: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
f490: 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
f4a0: 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#d
f4b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f4c0: 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
f4d0: 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   14  /* sqlite3_
f4e0: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20  pcache_methods* 
f4f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f500: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
f510: 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c  HE    15  /* sql
f520: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
f530: 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  ods* */../*.** C
f540: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
f550: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b  ration Options {
f560: 48 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30 3e  H10170} <S20000>
f570: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
f580: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
f590: 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
f5a0: 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
f5b0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f5c0: 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
f5d0: 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
f5e0: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
f5f0: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
f600: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
f610: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
f620: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
f630: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
f640: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
f650: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
f660: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
f670: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
f680: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
f690: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
f6a0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
f6b0: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
f6c0: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
f6d0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
f6e0: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
f6f0: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
f700: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
f710: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
f720: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
f730: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
f740: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
f750: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
f760: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
f770: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
f780: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f790: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
f7a0: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
f7b0: 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
f7c0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
f7d0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
f7e0: 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
f7f0: 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
f800: 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
f810: 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
f820: 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
f830: 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
f840: 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
f850: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f860: 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ion]..** The fir
f870: 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
f880: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
f890: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
f8a0: 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
f8b0: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
f8c0: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
f8d0: 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
f8e0: 65 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20 66  e memory.  The f
f8f0: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
f900: 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
f910: 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
f920: 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
f930: 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
f940: 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
f950: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
f960: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 65  lloc()].  The se
f970: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
f980: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
f990: 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
f9a0: 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
f9b0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
f9c0: 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  t is the number 
f9d0: 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68  of.** slots.  Th
f9e0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  e size of the bu
f9f0: 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  ffer in the firs
fa00: 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
fa10: 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a  be greater than.
fa20: 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74  ** or equal to t
fa30: 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68  he product of th
fa40: 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69  e second and thi
fa50: 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 3c 2f 64  rd arguments.</d
fa60: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
fa70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
fa80: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
fa90: 49 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20  IDE    1001  /* 
faa0: 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
fab0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
fac0: 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
fad0: 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
fae0: 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32 32  sult Codes {H122
faf0: 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  00} <S10700>.**.
fb00: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
fb10: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
fb20: 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
fb30: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
fb40: 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
fb50: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
fb60: 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
fb70: 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ite. The extende
fb80: 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
fb90: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
fba0: 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
fbb0: 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
fbc0: 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72 61  bility considera
fbd0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  tions..**.** INV
fbe0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
fbf0: 48 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65 77  H12201} Each new
fc00: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
fc10: 63 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61 76  ction] shall hav
fc20: 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  e the.**        
fc30: 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75    [extended resu
fc40: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
fc50: 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
fc60: 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fault..**.** {H1
fc70: 32 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  2202} The [sqlit
fc80: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
fc90: 6c 74 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20 69  lt_codes(D,F)] i
fca0: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 65  nterface shall e
fcb0: 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20  nable.**        
fcc0: 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75    [extended resu
fcd0: 6c 74 20 63 6f 64 65 73 5d 20 66 6f 72 20 74 68  lt codes] for th
fce0: 65 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  e  [database con
fcf0: 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20  nection] D.**   
fd00: 20 20 20 20 20 20 20 69 66 20 74 68 65 20 46 20         if the F 
fd10: 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 72 75  parameter is tru
fd20: 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  e, or disable th
fd30: 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73 65  em if F is false
fd40: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
fd50: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
fd60: 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
fd70: 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
fd80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
fd90: 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20  st Insert Rowid 
fda0: 7b 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30  {H12220} <S10700
fdb0: 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74  >.**.** Each ent
fdc0: 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
fdd0: 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
fde0: 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
fdf0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
fe00: 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69  called the "rowi
fe10: 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73  d". The rowid is
fe20: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
fe30: 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
fe40: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
fe50: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
fe60: 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
fe70: 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
fe80: 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
fe90: 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
fea0: 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
feb0: 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20  umns. If.** the 
fec0: 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
fed0: 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45 47  mn of type INTEG
fee0: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74  ER PRIMARY KEY t
fef0: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
ff00: 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
ff10: 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
ff20: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  d..**.** This ro
ff30: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
ff40: 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d  e rowid of the m
ff50: 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75  ost recent.** su
ff60: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
ff70: 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  ] into the datab
ff80: 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61  ase from the [da
ff90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ffa0: 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
ffb0: 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66  st argument.  If
ffc0: 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b   no successful [
ffd0: 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65  INSERT]s.** have
ffe0: 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
fff0: 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20  n that database 
10000 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f  connection, zero
10010 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
10020 0a 2a 2a 20 49 66 20 61 6e 20 5b 49 4e 53 45 52  .** If an [INSER
10030 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
10040 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e   a trigger, then
10050 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
10060 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
10070 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  w is returned by
10080 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73   this routine as
10090 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
100a0 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gger is running.
100b0 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
100c0 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61   trigger termina
100d0 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  tes, the value r
100e0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
100f0 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72  routine.** rever
10100 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76  ts to the last v
10110 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65  alue inserted be
10120 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
10130 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e   fired..**.** An
10140 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
10150 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
10160 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
10170 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
10180 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
10190 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
101a0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
101b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
101c0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54  s.** routine.  T
101d0 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
101e0 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
101f0 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
10200 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
10210 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
10220 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
10230 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
10240 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
10250 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
10260 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
10270 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54  ls.  When INSERT
10280 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
10290 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
102a0 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
102b0 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
102c0 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
102d0 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
102e0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
102f0 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
10300 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
10310 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
10320 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
10330 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
10340 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
10350 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
10360 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
10370 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68  ce..**.** For th
10380 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
10390 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
103a0 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
103b0 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
103c0 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
103d0 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
103e0 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
103f0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
10400 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32  TS:.**.** {H1222
10410 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
10420 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
10430 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  d()] function sh
10440 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 72  all return the r
10450 6f 77 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  owid.**         
10460 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   of the most rec
10470 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b  ent successful [
10480 49 4e 53 45 52 54 5d 20 70 65 72 66 6f 72 6d 65  INSERT] performe
10490 64 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  d on the same.**
104a0 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
104b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
104c0 61 6e 64 20 77 69 74 68 69 6e 20 74 68 65 20 73  and within the s
104d0 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 6c 65  ame or higher le
104e0 76 65 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  vel.**          
104f0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c  trigger context,
10500 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72   or zero if ther
10510 65 20 68 61 76 65 20 62 65 65 6e 20 6e 6f 20 71  e have been no q
10520 75 61 6c 69 66 79 69 6e 67 0a 2a 2a 20 20 20 20  ualifying.**    
10530 20 20 20 20 20 20 5b 49 4e 53 45 52 54 5d 20 73        [INSERT] s
10540 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
10550 20 7b 48 31 32 32 32 33 7d 20 54 68 65 20 5b 73   {H12223} The [s
10560 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
10570 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63  rt_rowid()] func
10580 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72  tion shall retur
10590 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
105a0 20 20 73 61 6d 65 20 76 61 6c 75 65 20 77 68 65    same value whe
105b0 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
105c0 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 20 63  e same trigger c
105d0 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20  ontext.**       
105e0 20 20 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62     immediately b
105f0 65 66 6f 72 65 20 61 6e 64 20 61 66 74 65 72 20  efore and after 
10600 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  a [ROLLBACK]..**
10610 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
10620 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 33 32 7d 20  .**.** {A12232} 
10630 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
10640 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
10650 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
10660 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
10670 20 20 20 20 20 64 61 74 61 62 61 73 65 20 63 6f       database co
10680 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
10690 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
106a0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
106b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
106c0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
106d0 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
106e0 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
106f0 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20  t rowid,.**     
10700 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 76 61       then the va
10710 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
10720 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
10730 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
10740 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 70  .**          unp
10750 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
10760 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
10770 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
10780 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20   the new.**     
10790 20 20 20 20 20 6c 61 73 74 20 69 6e 73 65 72 74       last insert
107a0 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74   rowid..*/.sqlit
107b0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
107c0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
107d0 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
107e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
107f0 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
10800 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
10810 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 30 36 30   {H12240} <S1060
10820 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
10830 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
10840 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
10850 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
10860 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
10870 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
10880 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
10890 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
108a0 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
108b0 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
108c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
108d0 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
108e0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
108f0 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68  eter..** Only ch
10900 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
10910 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
10920 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
10930 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
10940 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
10950 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
10960 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
10970 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
10980 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20  ** triggers are 
10990 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65  not counted. Use
109a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
109b0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
109c0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69  unction.** to fi
109d0 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
109e0 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
109f0 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
10a00 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
10a10 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f  ers..**.** A "ro
10a20 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
10a30 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
10a40 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
10a50 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
10a60 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
10a70 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
10a80 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
10a90 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
10aa0 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
10ab0 66 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43  ffects of REPLAC
10ac0 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
10ad0 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
10ae0 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
10af0 65 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42  essing, DROP TAB
10b00 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  LE, or by any ot
10b10 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
10b20 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
10b30 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
10b40 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  nges..**.** A "t
10b50 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
10b60 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
10b70 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
10b80 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
10b90 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
10ba0 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d  of a trigger.  M
10bb0 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
10bc0 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
10bd0 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
10be0 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
10bf0 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
10c00 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
10c10 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
10c20 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
10c30 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
10c40 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
10c50 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
10c60 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
10c70 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
10c80 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
10c90 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
10ca0 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
10cb0 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
10cc0 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
10cd0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
10ce0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
10cf0 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
10d00 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65   does.** not cre
10d10 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65  ate a new trigge
10d20 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
10d30 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
10d40 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
10d50 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20  r of direct row 
10d60 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a  changes in the.*
10d70 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  * most recent IN
10d80 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
10d90 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
10da0 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
10db0 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  e.** trigger con
10dc0 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73  text..**.** Thus
10dd0 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  , when called fr
10de0 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
10df0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
10e00 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e  returns the.** n
10e10 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
10e20 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
10e30 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
10e40 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
10e50 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72   that also occur
10e60 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c  red at the top l
10e70 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68  evel.  Within th
10e80 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
10e90 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ger,.** the sqli
10ea0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
10eb0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63  terface can be c
10ec0 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
10ed0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
10ee0 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
10ef0 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
10f00 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
10f10 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
10f20 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
10f30 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
10f40 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
10f50 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
10f60 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
10f70 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
10f80 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  de changes.** ca
10f90 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
10fa0 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20  ers since those 
10fb0 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
10fc0 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51  ontext..**.** SQ
10fd0 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
10fe0 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
10ff0 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
11000 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20  without a WHERE 
11010 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f  clause.** by dro
11020 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
11030 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
11040 20 44 6f 69 6e 67 20 73 6f 20 69 73 20 6d 75 63   Doing so is muc
11050 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f  h faster than go
11060 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  ing.** through a
11070 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69  nd deleting indi
11080 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20  vidual elements 
11090 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 20  from the table. 
110a0 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 69 73   Because of this
110b0 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  .** optimization
110c0 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20  , the deletions 
110d0 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  in "DELETE FROM 
110e0 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72  table" are not r
110f0 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a  ow changes and.*
11100 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f  * will not be co
11110 75 6e 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  unted by the sql
11120 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f  ite3_changes() o
11130 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  r [sqlite3_total
11140 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66  _changes()].** f
11150 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64  unctions, regard
11160 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62  less of the numb
11170 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74  er of elements t
11180 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61  hat were origina
11190 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61  lly.** in the ta
111a0 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20  ble.  To get an 
111b0 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f  accurate count o
111c0 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
111d0 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73  rows deleted, us
111e0 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  e.** "DELETE FRO
111f0 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22  M table WHERE 1"
11200 20 69 6e 73 74 65 61 64 2e 20 20 4f 72 20 72 65   instead.  Or re
11210 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67 20 74 68  compile using th
11220 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  e.** [SQLITE_OMI
11230 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50 54 49 4d  T_TRUNCATE_OPTIM
11240 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70 69 6c 65  IZATION] compile
11250 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 6f 20  -time option to 
11260 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 6f  disable the.** o
11270 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f 6e 20 61  ptimization on a
11280 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  ll queries..**.*
11290 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
112a0 0a 2a 2a 20 7b 48 31 32 32 34 31 7d 20 54 68 65  .** {H12241} The
112b0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
112c0 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  s()] function sh
112d0 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 6e  all return the n
112e0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20  umber of.**     
112f0 20 20 20 20 20 72 6f 77 20 63 68 61 6e 67 65 73       row changes
11300 20 63 61 75 73 65 64 20 62 79 20 74 68 65 20 6d   caused by the m
11310 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
11320 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 20 20  T, UPDATE,.**   
11330 20 20 20 20 20 20 20 6f 72 20 44 45 4c 45 54 45         or DELETE
11340 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68   statement on th
11350 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
11360 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 0a 2a  connection and.*
11370 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 69  *          withi
11380 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69  n the same or hi
11390 67 68 65 72 20 74 72 69 67 67 65 72 20 63 6f 6e  gher trigger con
113a0 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66  text, or zero if
113b0 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a 20 20   there have.**  
113c0 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e          not been
113d0 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e 67 20   any qualifying 
113e0 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  row changes..**.
113f0 2a 2a 20 7b 48 31 32 32 34 33 7d 20 53 74 61 74  ** {H12243} Stat
11400 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f  ements of the fo
11410 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  rm "DELETE FROM 
11420 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68 20  tablename" with 
11430 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 57  no.**          W
11440 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c  HERE clause shal
11450 6c 20 63 61 75 73 65 20 73 75 62 73 65 71 75 65  l cause subseque
11460 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20  nt calls to.**  
11470 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
11480 5f 63 68 61 6e 67 65 73 28 29 5d 20 74 6f 20 72  _changes()] to r
11490 65 74 75 72 6e 20 7a 65 72 6f 2c 20 72 65 67 61  eturn zero, rega
114a0 72 64 6c 65 73 73 20 6f 66 20 74 68 65 0a 2a 2a  rdless of the.**
114b0 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
114c0 20 6f 66 20 72 6f 77 73 20 6f 72 69 67 69 6e 61   of rows origina
114d0 6c 6c 79 20 69 6e 20 74 68 65 20 74 61 62 6c 65  lly in the table
114e0 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
114f0 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32  ONS:.**.** {A122
11500 35 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  52} If a separat
11510 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
11520 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
11530 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
11540 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
11550 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65     while [sqlite
11560 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
11570 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
11580 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
11590 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75  **          is u
115a0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
115b0 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
115c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
115d0 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
115e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
115f0 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
11600 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
11610 64 20 7b 48 31 32 32 36 30 7d 20 3c 53 31 30 36  d {H12260} <S106
11620 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  00>.**.** This f
11630 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
11640 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
11650 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
11660 20 62 79 20 49 4e 53 45 52 54 2c 0a 2a 2a 20 55   by INSERT,.** U
11670 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
11680 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
11690 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
116a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
116b0 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 63 6f  pened..** The co
116c0 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  unt includes all
116d0 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c   changes from al
116e0 6c 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  l trigger contex
116f0 74 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ts.  However,.**
11700 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
11710 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
11720 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ges used to impl
11730 65 6d 65 6e 74 20 52 45 50 4c 41 43 45 20 63 6f  ement REPLACE co
11740 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f  nstraints,.** do
11750 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42   rollbacks or AB
11760 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
11770 6f 72 20 44 52 4f 50 20 74 61 62 6c 65 20 70 72  or DROP table pr
11780 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68 65  ocessing..** The
11790 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75   changes are cou
117a0 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  nted as soon as 
117b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
117c0 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
117d0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28 77  .** completed (w
117e0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
117f0 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73  t handle is pass
11800 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
11810 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
11820 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
11830 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  )])..**.** SQLit
11840 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  e implements the
11850 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45   command "DELETE
11860 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74   FROM table" wit
11870 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61  hout a WHERE cla
11880 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69  use.** by droppi
11890 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e  ng and recreatin
118a0 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54  g the table.  (T
118b0 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 74  his is much fast
118c0 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a  er than going.**
118d0 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c   through and del
118e0 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c  eting individual
118f0 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74   elements from t
11900 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61  he table.)  Beca
11910 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f  use of this.** o
11920 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65  ptimization, the
11930 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44   deletions in "D
11940 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
11950 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68  " are not row ch
11960 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c  anges and.** wil
11970 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64  l not be counted
11980 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
11990 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71  changes() or [sq
119a0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
119b0 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  ges()].** functi
119c0 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20  ons, regardless 
119d0 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
119e0 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77   elements that w
119f0 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  ere originally.*
11a00 2a 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20  * in the table. 
11a10 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72   To get an accur
11a20 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65  ate count of the
11a30 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
11a40 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20  deleted, use.** 
11a50 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
11a60 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74  le WHERE 1" inst
11a70 65 61 64 2e 20 20 20 4f 72 20 72 65 63 6f 6d 70  ead.   Or recomp
11a80 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
11a90 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52   [SQLITE_OMIT_TR
11aa0 55 4e 43 41 54 45 5f 4f 50 54 49 4d 49 5a 41 54  UNCATE_OPTIMIZAT
11ab0 49 4f 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ION] compile-tim
11ac0 65 20 6f 70 74 69 6f 6e 20 74 6f 20 64 69 73 61  e option to disa
11ad0 62 6c 65 20 74 68 65 0a 2a 2a 20 6f 70 74 69 6d  ble the.** optim
11ae0 69 7a 61 74 69 6f 6e 20 6f 6e 20 61 6c 6c 20 71  ization on all q
11af0 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 65  ueries..**.** Se
11b00 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
11b10 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
11b20 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
11b30 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
11b40 2a 20 7b 48 31 32 32 36 31 7d 20 54 68 65 20 5b  * {H12261} The [
11b50 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
11b60 61 6e 67 65 73 28 29 5d 20 72 65 74 75 72 6e 73  anges()] returns
11b70 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
11b80 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  r.**          of
11b90 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
11ba0 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55  sed by INSERT, U
11bb0 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45  PDATE, and/or DE
11bc0 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 20 20  LETE.**         
11bd0 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74   statements on t
11be0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
11bf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69  e connection], i
11c00 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 20 20  n any.**        
11c10 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78    trigger contex
11c20 74 2c 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  t, since the dat
11c30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11c40 20 77 61 73 20 63 72 65 61 74 65 64 2e 0a 2a 2a   was created..**
11c50 0a 2a 2a 20 7b 48 31 32 32 36 33 7d 20 53 74 61  .** {H12263} Sta
11c60 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66  tements of the f
11c70 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  orm "DELETE FROM
11c80 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68   tablename" with
11c90 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   no.**          
11ca0 57 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61  WHERE clause sha
11cb0 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  ll not change th
11cc0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
11cd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
11ce0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
11cf0 68 61 6e 67 65 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a  hanges()]..**.**
11d00 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
11d10 0a 2a 2a 20 7b 41 31 32 32 36 34 7d 20 49 66 20  .** {A12264} If 
11d20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
11d30 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
11d40 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
11d50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
11d60 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c  **          whil
11d70 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
11d80 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
11d90 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
11da0 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20  value.**        
11db0 20 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e    returned is un
11dc0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
11dd0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
11de0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
11df0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
11e00 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
11e10 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
11e20 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
11e30 67 20 51 75 65 72 79 20 7b 48 31 32 32 37 30 7d  g Query {H12270}
11e40 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30500>.**.** 
11e50 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
11e60 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
11e70 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
11e80 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
11e90 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
11ea0 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
11eb0 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
11ec0 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
11ed0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
11ee0 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
11ef0 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
11f00 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
11f10 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
11f20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
11f30 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
11f40 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
11f50 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
11f60 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ly..**.** It is 
11f70 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
11f80 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
11f90 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
11fa0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
11fb0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
11fc0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
11fd0 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
11fe0 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
11ff0 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
12000 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
12010 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
12020 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12030 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
12040 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
12050 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
12060 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
12070 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  rns..**.** If an
12080 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
12090 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
120a0 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
120b0 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
120c0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
120d0 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
120e0 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
120f0 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
12100 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
12110 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
12120 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
12130 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  etion..**.** An 
12140 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
12150 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
12160 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
12170 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
12180 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65  ..** If the inte
12190 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
121a0 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
121b0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
121c0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
121d0 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
121e0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
121f0 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
12200 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
12210 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
12220 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
12230 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  y..**.** A call 
12240 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
12250 72 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66  rupt() has no ef
12260 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
12270 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
12280 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
12290 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
122a0 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
122b0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
122c0 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 31 7d 20 54  **.** {H12271} T
122d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  he [sqlite3_inte
122e0 72 72 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61  rrupt()] interfa
122f0 63 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c  ce will force al
12300 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20  l running.**    
12310 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
12320 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
12330 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 61  with the same da
12340 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12350 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  n.**          to
12360 20 68 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63   halt after proc
12370 65 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f  essing at most o
12380 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f  ne additional ro
12390 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
123a0 20 7b 48 31 32 32 37 32 7d 20 41 6e 79 20 53 51   {H12272} Any SQ
123b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
123c0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
123d0 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  by [sqlite3_inte
123e0 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20  rrupt()].**     
123f0 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e       will return
12400 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
12410 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  PT]..**.** ASSUM
12420 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
12430 31 32 32 37 39 7d 20 49 66 20 74 68 65 20 64 61  12279} If the da
12440 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12450 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
12460 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
12470 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  t()].**         
12480 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
12490 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
124a0 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
124b0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
124c0 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
124d0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
124e0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
124f0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
12500 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20  ent Is Complete 
12510 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30  {H10510} <S70200
12520 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
12530 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
12540 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69  l for command-li
12550 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
12560 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
12570 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
12580 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
12590 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20  form complete a 
125a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
125b0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
125c0 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
125d0 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
125e0 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
125f0 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
12600 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75  sing.  These rou
12610 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 72 75  tines return tru
12620 65 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  e if the input s
12630 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
12640 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
12650 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
12660 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73    A statement is
12670 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
12680 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
12690 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
126a0 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
126b0 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e  is not a fragmen
126c0 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54 45  t of a.** CREATE
126d0 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
126e0 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20  nt.  Semicolons 
126f0 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
12700 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
12710 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
12720 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
12730 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
12740 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
12750 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
12760 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
12770 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
12780 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
12790 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
127a0 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
127b0 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
127c0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
127d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
127e0 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
127f0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
12800 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
12810 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
12820 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
12830 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  t SQL..**.** INV
12840 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
12850 48 31 30 35 31 31 7d 20 41 20 73 75 63 63 65 73  H10511} A succes
12860 73 66 75 6c 20 65 76 61 6c 75 61 74 69 6f 6e 20  sful evaluation 
12870 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  of [sqlite3_comp
12880 6c 65 74 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  lete()] or.**   
12890 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
128a0 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 66 75  complete16()] fu
128b0 6e 63 74 69 6f 6e 73 20 73 68 61 6c 6c 0a 2a 2a  nctions shall.**
128c0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
128d0 20 61 20 6e 75 6d 65 72 69 63 20 31 20 69 66 20   a numeric 1 if 
128e0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
128f0 6c 61 73 74 20 6e 6f 6e 2d 77 68 69 74 65 73 70  last non-whitesp
12900 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ace.**          
12910 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 20 69  token in their i
12920 6e 70 75 74 20 69 73 20 61 20 73 65 6d 69 63 6f  nput is a semico
12930 6c 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20  lon that is not 
12940 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 20 20  in between.**   
12950 20 20 20 20 20 20 20 74 68 65 20 42 45 47 49 4e         the BEGIN
12960 20 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 43 52   and END of a CR
12970 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
12980 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tement..**.** {H
12990 31 30 35 31 32 7d 20 49 66 20 61 20 6d 65 6d 6f  10512} If a memo
129a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
129b0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
129c0 67 20 61 6e 20 69 6e 76 6f 63 61 74 69 6f 6e 0a  g an invocation.
129d0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 5b  **          of [
129e0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
129f0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
12a00 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 74 68  complete16()] th
12a10 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  en the.**       
12a20 20 20 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c     routine shall
12a30 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12a40 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53  NOMEM]..**.** AS
12a50 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
12a60 20 7b 41 31 30 35 31 32 7d 20 54 68 65 20 69 6e   {A10512} The in
12a70 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
12a80 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
12a90 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
12aa0 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
12ab0 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a    UTF-8 string..
12ac0 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 33 7d 20 54  **.** {A10513} T
12ad0 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
12ae0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
12af0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
12b00 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
12b10 20 20 20 20 20 20 20 20 20 55 54 46 2d 31 36 20           UTF-16 
12b20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
12b30 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
12b40 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
12b50 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
12b60 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
12b70 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
12b80 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
12b90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12ba0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
12bb0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
12bc0 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
12bd0 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34  s {H12310} <S404
12be0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
12bf0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
12c00 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
12c10 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
12c20 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a  voked whenever.*
12c30 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
12c40 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
12c50 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68  atabase table th
12c60 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
12c70 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
12c80 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a  has locked..**.*
12c90 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61  * If the busy ca
12ca0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
12cb0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
12cc0 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
12cd0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
12ce0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
12cf0 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
12d00 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
12d10 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 20  ck. If the busy 
12d20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
12d30 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
12d40 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20  e callback will 
12d50 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
12d60 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
12d70 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
12d80 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68  rgument to the h
12d90 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
12da0 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
12db0 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
12dc0 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
12dd0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
12de0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
12df0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
12e00 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68  ment to.** the h
12e10 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
12e20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
12e30 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
12e40 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
12e50 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
12e60 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
12e70 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65  g event.  If the
12e80 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
12e90 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
12ea0 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
12eb0 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
12ec0 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
12ed0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
12ee0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
12ef0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
12f00 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
12f10 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ned..** If the c
12f20 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
12f30 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
12f40 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
12f50 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
12f60 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
12f70 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
12f80 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
12f90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
12fa0 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
12fb0 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
12fc0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
12fd0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
12fe0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
12ff0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
13000 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65  on. If SQLite de
13010 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
13020 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
13030 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
13040 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
13050 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
13060 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
13070 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
13080 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
13090 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
130a0 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
130b0 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
130c0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
130d0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
130e0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
130f0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
13100 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
13110 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
13120 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
13130 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
13140 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
13150 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
13160 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
13170 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
13180 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
13190 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
131a0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
131b0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
131c0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
131d0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
131e0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
131f0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
13200 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
13210 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
13220 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
13230 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
13240 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
13250 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
13260 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
13270 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
13280 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
13290 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
132a0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
132b0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
132c0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
132d0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
132e0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
132f0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
13300 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
13310 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
13320 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
13330 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
13340 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  **.** The defaul
13350 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
13360 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  is NULL..**.** T
13370 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
13380 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
13390 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
133a0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
133b0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
133c0 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
133d0 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
133e0 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
133f0 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
13400 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
13410 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
13420 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
13430 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
13440 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
13450 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
13460 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
13470 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
13480 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
13490 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
134a0 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
134b0 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
134c0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
134d0 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
134e0 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
134f0 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20  ** readers.  If 
13500 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
13510 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b  promote the lock
13520 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65  , then the in-me
13530 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69  mory.** cache wi
13540 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e  ll be left in an
13550 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74   inconsistent st
13560 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65  ate and so the e
13570 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
13580 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68  promoted from th
13590 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e  e relatively ben
135a0 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  ign [SQLITE_BUSY
135b0 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ] to.** the more
135c0 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f   severe [SQLITE_
135d0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20  IOERR_BLOCKED]. 
135e0 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65   This error code
135f0 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
13600 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
13610 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
13620 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
13630 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
13640 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
13650 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
13660 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
13670 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
13680 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
13690 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
136a0 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
136b0 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
136c0 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
136d0 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20   There can only 
136e0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
136f0 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
13700 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
13710 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13720 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
13730 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
13740 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
13750 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
13760 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  dler.  Note that
13770 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
13780 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
13790 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73  ].** will also s
137a0 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20  et or clear the 
137b0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
137c0 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
137d0 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
137e0 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
137f0 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
13800 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
13810 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
13820 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
13830 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75  handler.  Any su
13840 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
13850 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
13860 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
13870 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
13880 2a 0a 2a 2a 20 7b 48 31 32 33 31 31 7d 20 54 68  *.** {H12311} Th
13890 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  e [sqlite3_busy_
138a0 68 61 6e 64 6c 65 72 28 44 2c 43 2c 41 29 5d 20  handler(D,C,A)] 
138b0 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72  function shall r
138c0 65 70 6c 61 63 65 0a 2a 2a 20 20 20 20 20 20 20  eplace.**       
138d0 20 20 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b     busy callback
138e0 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   in the [databas
138f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
13900 77 69 74 68 20 61 20 6e 65 77 0a 2a 2a 20 20 20  with a new.**   
13910 20 20 20 20 20 20 20 61 20 6e 65 77 20 62 75 73         a new bus
13920 79 20 68 61 6e 64 6c 65 72 20 43 20 61 6e 64 20  y handler C and 
13930 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
13940 20 70 6f 69 6e 74 65 72 20 41 2e 0a 2a 2a 0a 2a   pointer A..**.*
13950 2a 20 7b 48 31 32 33 31 32 7d 20 4e 65 77 6c 79  * {H12312} Newly
13960 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 62 61   created [databa
13970 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
13980 73 68 61 6c 6c 20 68 61 76 65 20 61 20 62 75 73  shall have a bus
13990 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61  y.**          ha
139a0 6e 64 6c 65 72 20 6f 66 20 4e 55 4c 4c 2e 0a 2a  ndler of NULL..*
139b0 2a 0a 2a 2a 20 7b 48 31 32 33 31 34 7d 20 57 68  *.** {H12314} Wh
139c0 65 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 5b  en two or more [
139d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
139e0 69 6f 6e 73 5d 20 73 68 61 72 65 20 61 0a 2a 2a  ions] share a.**
139f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
13a00 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
13a10 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e 20  _cache | common 
13a20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 20 20  cache],.**      
13a30 20 20 20 20 74 68 65 20 62 75 73 79 20 68 61 6e      the busy han
13a40 64 6c 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  dler for the dat
13a50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13a60 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
13a70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
13a80 20 63 61 63 68 65 20 73 68 61 6c 6c 20 62 65 20   cache shall be 
13a90 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
13aa0 20 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65 72   cache encounter
13ab0 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20  s a lock..**.** 
13ac0 7b 48 31 32 33 31 36 7d 20 49 66 20 61 20 62 75  {H12316} If a bu
13ad0 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
13ae0 61 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ack returns zero
13af0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69 74  , then the SQLit
13b00 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20  e interface.**  
13b10 20 20 20 20 20 20 20 20 74 68 61 74 20 70 72 6f          that pro
13b20 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e  voked the lockin
13b30 67 20 65 76 65 6e 74 20 73 68 61 6c 6c 20 72 65  g event shall re
13b40 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
13b50 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31  Y]..**.** {H1231
13b60 38 7d 20 53 51 4c 69 74 65 20 73 68 61 6c 6c 20  8} SQLite shall 
13b70 69 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 73 79  invokes the busy
13b80 20 68 61 6e 64 6c 65 72 20 77 69 74 68 20 74 77   handler with tw
13b90 6f 20 61 72 67 75 6d 65 6e 74 73 20 77 68 69 63  o arguments whic
13ba0 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  h.**          ar
13bb0 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  e a copy of the 
13bc0 70 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 65 64  pointer supplied
13bd0 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61   by the 3rd para
13be0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  meter to.**     
13bf0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75       [sqlite3_bu
13c00 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61 6e  sy_handler()] an
13c10 64 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 68 65  d a count of the
13c20 20 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72   number of prior
13c30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76  .**          inv
13c40 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
13c50 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
13c60 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
13c70 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41  g event..**.** A
13c80 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
13c90 2a 20 7b 41 31 32 33 31 39 7d 20 41 20 62 75 73  * {A12319} A bus
13ca0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
13cb0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
13cc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13cd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
13ce0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
13cf0 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
13d00 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
13d10 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
13d20 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
13d30 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
13d40 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
13d50 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
13d60 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
13d70 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34 30   Timeout {H12340
13d80 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a  } <S40410>.**.**
13d90 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65   This routine se
13da0 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
13db0 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
13dc0 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
13dd0 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
13de0 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
13df0 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
13e00 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
13e10 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a    The handler.**
13e20 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
13e30 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
13e40 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
13e50 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
13e60 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
13e70 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31  accumulated. {H1
13e80 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73 22  2343} After "ms"
13e90 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
13ea0 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
13eb0 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
13ec0 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
13ed0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
13ee0 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
13ef0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
13f00 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
13f10 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61  OCKED]..**.** Ca
13f20 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
13f30 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
13f40 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
13f50 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
13f60 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
13f70 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
13f80 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f  *.** There can o
13f90 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
13fa0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
13fb0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
13fc0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13fd0 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67  ction] any any g
13fe0 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
13ff0 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
14000 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
14010 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
14020 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
14030 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
14040 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
14050 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
14060 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
14070 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a   is cleared..**.
14080 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
14090 2a 0a 2a 2a 20 7b 48 31 32 33 34 31 7d 20 54 68  *.** {H12341} Th
140a0 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  e [sqlite3_busy_
140b0 74 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63 74  timeout()] funct
140c0 69 6f 6e 20 73 68 61 6c 6c 20 6f 76 65 72 72 69  ion shall overri
140d0 64 65 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20  de any prior.** 
140e0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
140f0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
14100 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75  ] or [sqlite3_bu
14110 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65  sy_handler()] se
14120 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tting.**        
14130 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64    on the same [d
14140 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14150 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  on]..**.** {H123
14160 34 33 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70  43} If the 2nd p
14170 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
14180 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
14190 74 28 29 5d 20 69 73 20 6c 65 73 73 20 74 68 61  t()] is less tha
141a0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
141b0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2c 20   equal to zero, 
141c0 74 68 65 6e 20 74 68 65 20 62 75 73 79 20 68 61  then the busy ha
141d0 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20 63  ndler shall be c
141e0 6c 65 61 72 65 64 20 73 6f 20 74 68 61 74 0a 2a  leared so that.*
141f0 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 20 73  *          all s
14200 75 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e  ubsequent lockin
14210 67 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 69 61  g events immedia
14220 74 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 51 4c  tely return [SQL
14230 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
14240 20 7b 48 31 32 33 34 34 7d 20 49 66 20 74 68 65   {H12344} If the
14250 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
14260 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  o [sqlite3_busy_
14270 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 61 20  timeout()] is a 
14280 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20  positive.**     
14290 20 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20 74       number N, t
142a0 68 65 6e 20 61 20 62 75 73 79 20 68 61 6e 64 6c  hen a busy handl
142b0 65 72 20 73 68 61 6c 6c 20 62 65 20 73 65 74 20  er shall be set 
142c0 74 68 61 74 20 72 65 70 65 61 74 65 64 6c 79 20  that repeatedly 
142d0 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20  calls.**        
142e0 20 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d    the xSleep() m
142f0 65 74 68 6f 64 20 69 6e 20 74 68 65 20 5b 73 71  ethod in the [sq
14300 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 20  lite3_vfs | VFS 
14310 69 6e 74 65 72 66 61 63 65 5d 20 75 6e 74 69 6c  interface] until
14320 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 69 74  .**          eit
14330 68 65 72 20 74 68 65 20 6c 6f 63 6b 20 63 6c 65  her the lock cle
14340 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ars or until the
14350 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65 65   cumulative slee
14360 70 20 74 69 6d 65 0a 2a 2a 20 20 20 20 20 20 20  p time.**       
14370 20 20 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b     reported back
14380 20 62 79 20 78 53 6c 65 65 70 28 29 20 65 78 63   by xSleep() exc
14390 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63 6f  eeds N milliseco
143a0 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nds..*/.int sqli
143b0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
143c0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
143d0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
143e0 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
143f0 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
14400 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b 48  nning Queries {H
14410 31 32 33 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a  12370} <S10000>.
14420 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
14430 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
14440 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
14450 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
14460 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
14470 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
14480 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
14490 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
144a0 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
144b0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
144c0 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
144d0 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
144e0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
144f0 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
14500 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
14510 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
14520 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
14530 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
14540 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
14550 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
14560 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
14570 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
14580 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
14590 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
145a0 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
145b0 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
145c0 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
145d0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
145e0 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
145f0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
14600 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
14610 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
14620 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
14630 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
14640 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
14650 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
14660 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
14670 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
14680 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
14690 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
146a0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
146b0 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
146c0 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
146d0 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
146e0 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
146f0 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
14700 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
14710 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
14720 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
14730 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
14740 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
14750 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
14760 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
14770 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
14780 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
14790 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
147a0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
147b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
147c0 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
147d0 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
147e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
147f0 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
14800 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
14810 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
14820 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
14830 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
14840 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
14850 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61  .**.** As an exa
14860 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
14870 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
14880 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
14890 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
148a0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
148b0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
148c0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
148d0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
148e0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
148f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
14900 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
14910 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
14920 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
14930 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
14940 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
14950 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
14960 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
14970 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
14980 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
14990 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
149a0 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
149b0 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
149c0 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
149d0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
149e0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
149f0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
14a00 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
14a10 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
14a20 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
14a30 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
14a40 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
14a50 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
14a60 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
14a70 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
14a80 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
14a90 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
14aa0 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
14ab0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
14ac0 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
14ad0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
14ae0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
14af0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
14b00 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
14b10 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
14b20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14b30 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
14b40 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
14b50 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
14b60 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
14b70 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
14b80 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
14b90 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
14ba0 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
14bb0 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
14bc0 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
14bd0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
14be0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
14bf0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
14c00 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
14c10 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74  rameter.  It ret
14c20 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
14c30 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
14c40 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
14c50 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
14c60 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
14c70 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
14c80 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
14c90 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  using the result
14ca0 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70  , it should.** p
14cb0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20  ass the pointer 
14cc0 74 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  to the result ta
14cd0 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ble to sqlite3_f
14ce0 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
14cf0 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
14d00 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
14d10 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
14d20 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
14d30 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
14d40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
14d50 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
14d60 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
14d70 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
14d80 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
14d90 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
14da0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
14db0 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
14dc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
14dd0 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
14de0 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
14df0 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
14e00 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
14e10 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
14e20 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
14e30 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
14e40 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
14e50 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
14e60 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
14e70 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
14e80 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
14e90 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
14ea0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
14eb0 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
14ec0 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
14ed0 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
14ee0 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
14ef0 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
14f00 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
14f10 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
14f20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
14f30 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
14f40 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
14f50 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
14f60 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
14f70 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
14f80 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
14f90 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
14fa0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
14fb0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
14fc0 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  msg()]..**.** IN
14fd0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
14fe0 7b 48 31 32 33 37 31 7d 20 49 66 20 61 20 5b 73  {H12371} If a [s
14ff0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
15000 28 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f  ()] fails a memo
15010 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  ry allocation, t
15020 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
15030 69 74 20 73 68 61 6c 6c 20 66 72 65 65 20 74 68  it shall free th
15040 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 75  e result table u
15050 6e 64 65 72 20 63 6f 6e 73 74 72 75 63 74 69 6f  nder constructio
15060 6e 2c 20 61 62 6f 72 74 20 74 68 65 0a 2a 2a 20  n, abort the.** 
15070 20 20 20 20 20 20 20 20 20 71 75 65 72 79 20 69           query i
15080 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 70 20  n process, skip 
15090 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 71  any subsequent q
150a0 75 65 72 69 65 73 2c 20 73 65 74 20 74 68 65 0a  ueries, set the.
150b0 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 70 61 7a  **          *paz
150c0 52 65 73 75 6c 74 20 6f 75 74 70 75 74 20 70 6f  Result output po
150d0 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e  inter to NULL an
150e0 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
150f0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  _NOMEM]..**.** {
15100 48 31 32 33 37 33 7d 20 49 66 20 74 68 65 20 70  H12373} If the p
15110 6e 43 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65  nColumn paramete
15120 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65  r to [sqlite3_ge
15130 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f  t_table()] is no
15140 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  t NULL.**       
15150 20 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73     then a succes
15160 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
15170 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  of [sqlite3_get_
15180 74 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a  table()] shall.*
15190 2a 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65  *          write
151a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
151b0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
151c0 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74            result
151d0 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72   set of the quer
151e0 79 20 69 6e 74 6f 20 2a 70 6e 43 6f 6c 75 6d 6e  y into *pnColumn
151f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 34 7d  ..**.** {H12374}
15200 20 49 66 20 74 68 65 20 70 6e 52 6f 77 20 70 61   If the pnRow pa
15210 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
15220 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
15230 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20   is not NULL.** 
15240 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 61 20           then a 
15250 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
15260 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
15270 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73  3_get_table()] s
15280 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
15290 20 77 72 69 74 65 73 20 74 68 65 20 6e 75 6d 62   writes the numb
152a0 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 74 68  er of rows in th
152b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
152c0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20  sult set of the 
152d0 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 52 6f  query into *pnRo
152e0 77 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 36  w..**.** {H12376
152f0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
15300 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
15310 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
15320 29 5d 20 74 68 61 74 20 63 6f 6d 70 75 74 65 73  )] that computes
15330 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 20 72  .**          N r
15340 6f 77 73 20 6f 66 20 72 65 73 75 6c 74 20 77 69  ows of result wi
15350 74 68 20 43 20 63 6f 6c 75 6d 6e 73 20 70 65 72  th C columns per
15360 20 72 6f 77 20 73 68 61 6c 6c 20 6d 61 6b 65 20   row shall make 
15370 2a 70 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 20 20  *pazResult.**   
15380 20 20 20 20 20 20 20 70 6f 69 6e 74 20 74 6f 20         point to 
15390 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
153a0 74 65 72 73 20 74 6f 20 28 4e 2b 31 29 2a 43 20  ters to (N+1)*C 
153b0 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 74 68  strings where th
153c0 65 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20  e first.**      
153d0 20 20 20 20 43 20 73 74 72 69 6e 67 73 20 61 72      C strings ar
153e0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 61  e column names a
153f0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  s obtained from.
15400 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
15410 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
15420 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 74  ()] and the rest
15430 20 61 72 65 20 63 6f 6c 75 6d 6e 20 72 65 73 75   are column resu
15440 6c 74 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  lt values.**    
15450 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66        obtained f
15460 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
15470 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
15480 2a 2a 20 7b 48 31 32 33 37 39 7d 20 54 68 65 20  ** {H12379} The 
15490 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 70 61  values in the pa
154a0 7a 52 65 73 75 6c 74 20 61 72 72 61 79 20 72 65  zResult array re
154b0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
154c0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a  e3_get_table()].
154d0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
154e0 6c 20 72 65 6d 61 69 6e 20 76 61 6c 69 64 20 75  l remain valid u
154f0 6e 74 69 6c 20 63 6c 65 61 72 65 64 20 62 79 20  ntil cleared by 
15500 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
15510 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ble()]..**.** {H
15520 31 32 33 38 32 7d 20 57 68 65 6e 20 61 6e 20 65  12382} When an e
15530 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
15540 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  ng evaluation of
15550 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
15560 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ble()].**       
15570 20 20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20     the function 
15580 73 68 61 6c 6c 20 73 65 74 20 2a 70 61 7a 52 65  shall set *pazRe
15590 73 75 6c 74 20 74 6f 20 4e 55 4c 4c 2c 20 77 72  sult to NULL, wr
155a0 69 74 65 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ite an error mes
155b0 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  sage.**         
155c0 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
155d0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
155e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 6d  te3_malloc()], m
155f0 61 6b 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ake.**          
15600 2a 2a 70 7a 45 72 72 6d 73 67 20 70 6f 69 6e 74  **pzErrmsg point
15610 20 74 6f 20 74 68 61 74 20 65 72 72 6f 72 20 6d   to that error m
15620 65 73 73 61 67 65 2c 20 61 6e 64 20 72 65 74 75  essage, and retu
15630 72 6e 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  rn a.**         
15640 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
15650 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e  ror code]..*/.in
15660 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
15670 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
15680 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
15690 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
156a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
156b0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
156c0 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
156d0 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
156e0 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
156f0 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
15700 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
15710 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
15720 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
15730 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
15740 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
15750 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
15760 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
15770 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
15780 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
15790 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
157a0 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
157b0 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
157c0 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
157d0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
157e0 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
157f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
15800 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
15810 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
15820 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c 53 37 30  ns {H17400} <S70
15830 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a  000><S20000>.**.
15840 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
15850 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73  s are workalikes
15860 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
15870 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
15880 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
15890 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
158a0 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  brary..**.** The
158b0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
158c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
158d0 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
158e0 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
158f0 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
15900 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
15910 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
15920 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
15930 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
15940 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
15950 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
15960 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
15970 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
15980 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20    Both routines 
15990 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
159a0 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
159b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
159c0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
159d0 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
159e0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
159f0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
15a00 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c  ng..**.** In sql
15a10 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
15a20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
15a30 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
15a40 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
15a50 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
15a60 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
15a70 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
15a80 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
15a90 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
15aa0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
15ab0 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
15ac0 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
15ad0 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
15ae0 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
15af0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
15b00 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
15b10 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
15b20 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68   snprintf().  Th
15b30 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
15b40 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
15b50 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
15b60 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
15b70 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
15b80 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
15b90 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61  .  Note also tha
15ba0 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
15bb0 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
15bc0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
15bd0 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
15be0 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
15bf0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
15c00 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
15c10 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
15c20 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
15c30 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
15c40 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
15c50 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
15c60 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
15c70 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
15c80 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
15c90 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
15ca0 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
15cb0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
15cc0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
15cd0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
15ce0 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73  **.** As long as
15cf0 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
15d00 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
15d10 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
15d20 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
15d30 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
15d40 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
15d50 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
15d60 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  d.  The first.**
15d70 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
15d80 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
15d90 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
15da0 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
15db0 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
15dc0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
15dd0 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
15de0 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
15df0 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
15e00 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
15e10 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
15e20 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
15e30 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
15e40 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
15e50 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
15e60 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
15e70 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
15e80 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
15e90 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
15ea0 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
15eb0 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
15ec0 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
15ed0 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
15ee0 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
15ef0 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
15f00 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
15f10 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
15f20 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
15f30 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
15f40 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e  es a null-termin
15f50 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
15f60 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
15f70 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
15f80 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
15f90 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
15fa0 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
15fb0 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
15fc0 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
15fd0 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e  ral.  By doublin
15fe0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
15ff0 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
16000 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
16010 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
16020 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
16030 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
16040 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
16050 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
16060 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
16070 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
16080 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
16090 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
160a0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
160b0 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
160c0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
160d0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
160e0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
160f0 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
16100 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
16110 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
16120 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
16130 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
16140 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
16150 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
16160 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
16170 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
16180 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
16190 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
161a0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
161b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
161c0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
161d0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
161e0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
161f0 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
16200 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
16210 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
16220 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
16230 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
16240 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
16250 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
16260 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
16270 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
16280 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
16290 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
162a0 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
162b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
162c0 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
162d0 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
162e0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
162f0 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
16300 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
16310 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
16320 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
16330 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
16340 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
16350 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
16360 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
16370 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
16380 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
16390 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
163a0 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
163b0 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
163c0 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
163d0 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
163e0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
163f0 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
16400 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
16410 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
16420 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f  .** The %Q optio
16430 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
16440 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
16450 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
16460 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
16470 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
16480 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
16490 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
164a0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
164b0 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
164c0 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
164d0 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
164e0 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
164f0 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
16500 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
16510 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  ) in place of th
16520 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f  e %Q option.  So
16530 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
16540 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
16550 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
16560 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
16570 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
16580 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
16590 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
165a0 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
165b0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
165c0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
165d0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
165e0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
165f0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
16600 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
16610 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
16620 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
16630 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
16640 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
16650 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
16660 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
16670 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
16680 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22  ..**.** The "%z"
16690 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
166a0 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79  on works exactly
166b0 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68 20   like "%s" with 
166c0 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
166d0 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
166e0 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
166f0 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
16700 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
16710 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
16720 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
16730 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
16740 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49  g. {END}.**.** I
16750 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
16760 20 7b 48 31 37 34 30 33 7d 20 20 54 68 65 20 5b   {H17403}  The [
16770 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
16780 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
16790 76 6d 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  vmprintf()] inte
167a0 72 66 61 63 65 73 0a 2a 2a 20 20 20 20 20 20 20  rfaces.**       
167b0 20 20 20 20 72 65 74 75 72 6e 20 65 69 74 68 65      return eithe
167c0 72 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  r pointers to ze
167d0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
167e0 46 2d 38 20 73 74 72 69 6e 67 73 20 68 65 6c 64  F-8 strings held
167f0 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   in.**          
16800 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
16810 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
16820 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 4c 4c  alloc()] or NULL
16830 20 70 6f 69 6e 74 65 72 73 20 69 66 0a 2a 2a 20   pointers if.** 
16840 20 20 20 20 20 20 20 20 20 20 61 20 63 61 6c 6c            a call
16850 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
16860 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e 0a 2a 2a  loc()] fails..**
16870 0a 2a 2a 20 7b 48 31 37 34 30 36 7d 20 20 54 68  .** {H17406}  Th
16880 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  e [sqlite3_snpri
16890 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ntf()] interface
168a0 20 77 72 69 74 65 73 20 61 20 7a 65 72 6f 2d 74   writes a zero-t
168b0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20  erminated.**    
168c0 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72         UTF-8 str
168d0 69 6e 67 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ing into the buf
168e0 66 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  fer pointed to b
168f0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
16900 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ameter.**       
16910 20 20 20 20 70 72 6f 76 69 64 65 64 20 74 68 61      provided tha
16920 74 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  t the first para
16930 6d 65 74 65 72 20 69 73 20 67 72 65 61 74 65 72  meter is greater
16940 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a   than zero..**.*
16950 2a 20 7b 48 31 37 34 30 37 7d 20 20 54 68 65 20  * {H17407}  The 
16960 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
16970 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  f()] interface d
16980 6f 65 73 20 6e 6f 74 20 77 72 69 74 65 20 73 6c  oes not write sl
16990 6f 74 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ots of.**       
169a0 20 20 20 20 69 74 73 20 6f 75 74 70 75 74 20 62      its output b
169b0 75 66 66 65 72 20 28 74 68 65 20 73 65 63 6f 6e  uffer (the secon
169c0 64 20 70 61 72 61 6d 65 74 65 72 29 20 6f 75 74  d parameter) out
169d0 73 69 64 65 20 74 68 65 20 72 61 6e 67 65 0a 2a  side the range.*
169e0 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 20 30  *           of 0
169f0 20 74 68 72 6f 75 67 68 20 4e 2d 31 20 28 77 68   through N-1 (wh
16a00 65 72 65 20 4e 20 69 73 20 74 68 65 20 66 69 72  ere N is the fir
16a10 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
16a20 20 20 20 20 20 20 20 20 20 20 20 72 65 67 61 72             regar
16a30 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6c 65 6e  dless of the len
16a40 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
16a50 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  g.**           r
16a60 65 71 75 65 73 74 65 64 20 62 79 20 74 68 65 20  equested by the 
16a70 66 6f 72 6d 61 74 20 73 70 65 63 69 66 69 63 61  format specifica
16a80 74 69 6f 6e 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73  tion..*/.char *s
16a90 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
16aa0 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
16ab0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
16ac0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
16ad0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
16ae0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
16af0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
16b00 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
16b10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16b20 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
16b30 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20  ation Subsystem 
16b40 7b 48 31 37 33 30 30 7d 20 3c 53 32 30 30 30 30  {H17300} <S20000
16b50 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  >.**.** The SQLi
16b60 74 65 20 63 6f 72 65 20 20 75 73 65 73 20 74 68  te core  uses th
16b70 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
16b80 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
16b90 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
16ba0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
16bb0 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
16bc0 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
16bd0 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
16be0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
16bf0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
16c00 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
16c10 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
16c20 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
16c30 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
16c40 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
16c50 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
16c60 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
16c70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16c80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
16c90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
16ca0 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
16cb0 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
16cc0 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
16cd0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
16ce0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73  rameter..** If s
16cf0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
16d00 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
16d10 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
16d20 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
16d30 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
16d40 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68   pointer.  If th
16d50 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
16d60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
16d70 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
16d80 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
16d90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
16da0 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
16db0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
16dc0 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
16dd0 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
16de0 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
16df0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
16e00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16e10 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
16e20 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
16e30 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
16e40 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
16e50 65 20 72 65 75 73 65 64 2e 20 20 54 68 65 20 73  e reused.  The s
16e60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
16e70 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
16e80 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
16e90 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
16ea0 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
16eb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
16ec0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
16ed0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
16ee0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
16ef0 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
16f00 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
16f10 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
16f20 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
16f30 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
16f40 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
16f50 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
16f60 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
16f70 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
16f80 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
16f90 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
16fa0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
16fb0 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
16fc0 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
16fd0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
16fe0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
16ff0 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
17000 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
17010 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
17020 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
17030 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
17040 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17050 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
17060 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
17070 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
17080 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
17090 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
170a0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
170b0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
170c0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
170d0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
170e0 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
170f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
17100 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
17110 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
17120 65 72 2e 20 20 49 66 20 74 68 65 20 66 69 72 73  er.  If the firs
17130 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
17140 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17150 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
17160 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
17170 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
17180 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
17190 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
171a0 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
171b0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
171c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
171d0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66  realloc()..** If
171e0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
171f0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
17200 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
17210 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
17220 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
17230 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
17240 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
17250 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
17260 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
17270 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
17280 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
17290 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71  realloc()..** sq
172a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
172b0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
172c0 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
172d0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
172e0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
172f0 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
17300 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  if sufficient me
17310 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61  mory is unavaila
17320 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20  ble..** If M is 
17330 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
17340 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
17350 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
17360 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
17370 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
17380 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
17390 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
173a0 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
173b0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
173c0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
173d0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
173e0 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
173f0 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
17400 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  oc() returns NUL
17410 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f  L, then the prio
17420 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  r allocation.** 
17430 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
17440 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72  .** The memory r
17450 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
17460 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
17470 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17480 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
17490 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
174a0 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
174b0 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  ndary. {END}.**.
174c0 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 69  ** The default i
174d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
174e0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
174f0 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
17500 20 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c   uses.** the mal
17510 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
17520 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76   and free() prov
17530 69 64 65 64 20 62 79 20 74 68 65 20 73 74 61 6e  ided by the stan
17540 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
17550 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f 77 65  ** {H17382} Howe
17560 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
17570 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
17580 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45  the.** SQLITE_ME
17590 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e  MORY_SIZE=<i>NNN
175a0 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f 63 65 73  </i> C preproces
175b0 73 6f 72 20 6d 61 63 72 6f 20 28 77 68 65 72 65  sor macro (where
175c0 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69   <i>NNN</i>.** i
175d0 73 20 61 6e 20 69 6e 74 65 67 65 72 29 2c 20 74  s an integer), t
175e0 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74  hen SQLite creat
175f0 65 20 61 20 73 74 61 74 69 63 20 61 72 72 61 79  e a static array
17600 20 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20   of at least.** 
17610 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73  <i>NNN</i> bytes
17620 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65   in size and use
17630 73 20 74 68 61 74 20 61 72 72 61 79 20 66 6f 72  s that array for
17640 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
17650 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  mic.** memory al
17660 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
17670 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61  {END}  Additiona
17680 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
17690 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61  or options.** ma
176a0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
176b0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
176c0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
176d0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
176e0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
176f0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
17700 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
17710 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
17720 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
17730 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
17740 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
17750 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
17760 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
17770 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
17780 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
17790 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
177a0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
177b0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
177c0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
177d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64  ..**.** The Wind
177e0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
177f0 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   layer calls.** 
17800 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
17810 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
17820 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
17830 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
17840 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
17850 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
17860 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
17870 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
17880 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
17890 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
178a0 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
178b0 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
178c0 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
178d0 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72  cation errors ar
178e0 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
178f0 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f  ** they are repo
17900 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
17910 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
17920 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
17930 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
17940 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
17950 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
17960 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 33 7d  :.**.** {H17303}
17970 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
17980 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66  alloc(N)] interf
17990 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
179a0 65 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  er a pointer to.
179b0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 6e  **           a n
179c0 65 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75 74  ewly checked-out
179d0 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65 61   block of at lea
179e0 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  st N bytes of me
179f0 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  mory.**         
17a00 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65    that is 8-byte
17a10 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 69 74 20   aligned, or it 
17a20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
17a30 69 74 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20  it is unable.** 
17a40 20 20 20 20 20 20 20 20 20 20 74 6f 20 66 75 6c            to ful
17a50 66 69 6c 6c 20 74 68 65 20 72 65 71 75 65 73 74  fill the request
17a60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 34 7d  ..**.** {H17304}
17a70 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
17a80 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66  alloc(N)] interf
17a90 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ace returns a NU
17aa0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a  LL pointer if.**
17ab0 20 20 20 20 20 20 20 20 20 20 20 4e 20 69 73 20             N is 
17ac0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
17ad0 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  al to zero..**.*
17ae0 2a 20 7b 48 31 37 33 30 35 7d 20 20 54 68 65 20  * {H17305}  The 
17af0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29  [sqlite3_free(P)
17b00 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 6c 65  ] interface rele
17b10 61 73 65 73 20 6d 65 6d 6f 72 79 20 70 72 65 76  ases memory prev
17b20 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20  iously.**       
17b30 20 20 20 20 72 65 74 75 72 6e 65 64 20 66 72 6f      returned fro
17b40 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
17b50 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
17b60 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  _realloc()],.** 
17b70 20 20 20 20 20 20 20 20 20 20 6d 61 6b 69 6e 67            making
17b80 20 69 74 20 61 76 61 69 6c 61 62 6c 65 20 66 6f   it available fo
17b90 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b  r reuse..**.** {
17ba0 48 31 37 33 30 36 7d 20 20 41 20 63 61 6c 6c 20  H17306}  A call 
17bb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
17bc0 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68 61 72  (NULL)] is a har
17bd0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
17be0 2a 2a 20 7b 48 31 37 33 31 30 7d 20 20 41 20 63  ** {H17310}  A c
17bf0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
17c00 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73  realloc(0,N)] is
17c10 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61   equivalent to a
17c20 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20   call.**        
17c30 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d     to [sqlite3_m
17c40 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  alloc(N)]..**.**
17c50 20 7b 48 31 37 33 31 32 7d 20 20 41 20 63 61 6c   {H17312}  A cal
17c60 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
17c70 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20 65  alloc(P,0)] is e
17c80 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63  quivalent to a c
17c90 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
17ca0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
17cb0 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  e(P)]..**.** {H1
17cc0 37 33 31 35 7d 20 20 54 68 65 20 53 51 4c 69 74  7315}  The SQLit
17cd0 65 20 63 6f 72 65 20 75 73 65 73 20 5b 73 71 6c  e core uses [sql
17ce0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
17cf0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
17d00 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
17d10 20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66    and [sqlite3_f
17d20 72 65 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f  ree()] for all o
17d30 66 20 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  f its memory all
17d40 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20  ocation and.**  
17d50 20 20 20 20 20 20 20 20 20 64 65 61 6c 6c 6f 63           dealloc
17d60 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a  ation needs..**.
17d70 2a 2a 20 7b 48 31 37 33 31 38 7d 20 20 54 68 65  ** {H17318}  The
17d80 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
17d90 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  c(P,N)] interfac
17da0 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
17db0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
17dc0 20 20 20 20 20 20 20 20 74 6f 20 61 20 62 6c 6f          to a blo
17dd0 63 6b 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75  ck of checked-ou
17de0 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c  t memory of at l
17df0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
17e00 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  size.**         
17e10 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65    that is 8-byte
17e20 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e   aligned, or a N
17e30 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
17e40 2a 2a 20 7b 48 31 37 33 32 31 7d 20 20 57 68 65  ** {H17321}  Whe
17e50 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  n [sqlite3_reall
17e60 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73  oc(P,N)] returns
17e70 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
17e80 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a  ter, it first.**
17e90 20 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65             copie
17ea0 73 20 74 68 65 20 66 69 72 73 74 20 4b 20 62 79  s the first K by
17eb0 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66  tes of content f
17ec0 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68 65 20 6e  rom P into the n
17ed0 65 77 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ewly.**         
17ee0 20 20 61 6c 6c 6f 63 61 74 65 64 20 62 6c 6f 63    allocated bloc
17ef0 6b 2c 20 77 68 65 72 65 20 4b 20 69 73 20 74 68  k, where K is th
17f00 65 20 6c 65 73 73 65 72 20 6f 66 20 4e 20 61 6e  e lesser of N an
17f10 64 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  d the size of.**
17f20 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62             the b
17f30 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b  uffer P..**.** {
17f40 48 31 37 33 32 32 7d 20 20 57 68 65 6e 20 5b 73  H17322}  When [s
17f50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
17f60 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e  ,N)] returns a n
17f70 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
17f80 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20   it first.**    
17f90 20 20 20 20 20 20 20 72 65 6c 65 61 73 65 73 20         releases 
17fa0 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  the buffer P..**
17fb0 0a 2a 2a 20 7b 48 31 37 33 32 33 7d 20 20 57 68  .** {H17323}  Wh
17fc0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
17fd0 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
17fe0 73 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66 66  s NULL, the buff
17ff0 65 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 20  er P is.**      
18000 20 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65       not modifie
18010 64 20 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a  d or released..*
18020 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
18030 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 30 7d  :.**.** {A17350}
18040 20 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72    The pointer ar
18050 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
18060 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
18070 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
18080 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
18090 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
180a0 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
180b0 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
180c0 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 20  rom a prior.**  
180d0 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74           invocat
180e0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
180f0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
18100 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
18110 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 20 20   that have.**   
18120 20 20 20 20 20 20 20 20 6e 6f 74 20 79 65 74 20          not yet 
18130 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
18140 2a 0a 2a 2a 20 7b 41 31 37 33 35 31 7d 20 20 54  *.** {A17351}  T
18150 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
18160 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
18170 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
18180 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  f.**           a
18190 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
181a0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
181b0 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
181c0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  g.**           [
181d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
181e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
181f0 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
18200 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
18210 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
18220 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
18230 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
18240 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
18250 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18260 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
18270 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 20  ator Statistics 
18280 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31 30  {H17370} <S30210
18290 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  >.**.** SQLite p
182a0 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
182b0 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
182c0 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
182d0 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
182e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
182f0 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
18300 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
18310 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
18320 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
18330 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
18340 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
18350 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
18360 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  m..**.** INVARIA
18370 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  NTS:.**.** {H173
18380 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  71} The [sqlite3
18390 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
183a0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
183b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
183c0 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
183d0 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
183e0 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
183f0 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
18400 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20  t freed)..**.** 
18410 7b 48 31 37 33 37 33 7d 20 54 68 65 20 5b 73 71  {H17373} The [sq
18420 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
18430 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
18440 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
18450 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20 20  ximum.**        
18460 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69    value of [sqli
18470 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
18480 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
18490 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
184a0 20 20 20 20 20 20 20 20 20 77 61 73 20 6c 61 73           was las
184b0 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b  t reset..**.** {
184c0 48 31 37 33 37 34 7d 20 54 68 65 20 76 61 6c 75  H17374} The valu
184d0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
184e0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
184f0 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  sed()] and.**   
18500 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
18510 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
18520 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
18530 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 20 20  overhead.**     
18540 20 20 20 20 20 61 64 64 65 64 20 62 79 20 53 51       added by SQ
18550 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
18560 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
18570 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18580 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75  ,.**          bu
18590 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
185a0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
185b0 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
185c0 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20 20  m library.**    
185d0 20 20 20 20 20 20 72 6f 75 74 69 6e 65 73 20 74        routines t
185e0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
185f0 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
18600 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 35 7d 20  .**.** {H17375} 
18610 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
18620 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
18630 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
18640 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20  nt value of.**  
18650 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
18660 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
18670 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
18680 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
18690 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
186a0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
186b0 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
186c0 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  .  The value ret
186d0 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  urned.**        
186e0 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65    by [sqlite3_me
186f0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
18700 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
18710 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20  ater mark.**    
18720 20 20 20 20 20 20 70 72 69 6f 72 20 74 6f 20 74        prior to t
18730 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
18740 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
18750 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
18760 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
18770 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
18780 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
18790 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
187a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
187b0 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
187c0 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 48 31  er Generator {H1
187d0 37 33 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  7390} <S20000>.*
187e0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
187f0 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
18800 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
18810 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
18820 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
18830 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
18840 6f 6d 20 52 4f 57 49 44 73 20 77 68 65 6e 20 69  om ROWIDs when i
18850 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
18860 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
18870 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
18880 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
18890 73 74 20 70 6f 73 73 69 62 6c 65 20 52 4f 57 49  st possible ROWI
188a0 44 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  D.  The PRNG is 
188b0 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
188c0 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
188d0 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
188e0 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
188f0 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
18900 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
18910 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
18920 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
18930 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
18940 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
18950 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
18960 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
18970 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
18980 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
18990 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  P..**.** The fir
189a0 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
189b0 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
189c0 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
189d0 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
189e0 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
189f0 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
18a00 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
18a10 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
18a20 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
18a30 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
18a40 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
18a50 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
18a60 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65   On all subseque
18a70 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20  nt invocations, 
18a80 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
18a90 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
18aa0 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
18ab0 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
18ac0 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
18ad0 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
18ae0 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
18af0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
18b00 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 39  TS:.**.** {H1739
18b10 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
18b20 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 5d  randomness(N,P)]
18b30 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65   interface write
18b40 73 20 4e 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20  s N bytes of.** 
18b50 20 20 20 20 20 20 20 20 20 68 69 67 68 2d 71 75           high-qu
18b60 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
18b70 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
18b80 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fer P..*/.void s
18b90 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
18ba0 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
18bb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18bc0 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
18bd0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
18be0 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 35 30 30  allbacks {H12500
18bf0 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70100>.**.**
18c00 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
18c10 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72  gisters a author
18c20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
18c30 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
18c40 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
18c50 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
18c60 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
18c70 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
18c80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18c90 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
18ca0 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
18cb0 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
18cc0 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
18cd0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
18ce0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
18cf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18d00 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
18d10 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
18d20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
18d30 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41  pare16_v2()].  A
18d40 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
18d50 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
18d60 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
18d70 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
18d80 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
18d90 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
18da0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
18db0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18dc0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
18dd0 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
18de0 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
18df0 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74  llowed.  The aut
18e00 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18e10 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
18e20 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
18e30 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
18e40 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
18e50 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
18e60 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
18e70 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
18e80 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
18e90 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
18ea0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
18eb0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
18ec0 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
18ed0 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
18ee0 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
18ef0 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
18f00 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61 75 74  ror.  If the aut
18f10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18f20 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
18f30 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
18f40 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
18f50 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
18f60 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
18f70 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
18f80 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
18f90 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
18fa0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
18fb0 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
18fc0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
18fd0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
18fe0 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
18ff0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
19000 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
19010 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
19020 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
19030 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
19040 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  .  When the call
19050 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
19060 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
19070 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
19080 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
19090 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
190a0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
190b0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
190c0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
190d0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
190e0 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
190f0 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
19100 64 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f  d.  If the autho
19110 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53  rizer code is [S
19120 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
19130 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
19140 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
19150 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
19160 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
19170 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
19180 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
19190 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
191a0 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
191b0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
191c0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
191d0 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
191e0 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
191f0 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
19200 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
19210 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
19220 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
19230 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
19240 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
19250 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
19260 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
19270 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a   of a table..**.
19280 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
19290 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
192a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
192b0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
192c0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
192d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
192e0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
192f0 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
19300 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
19310 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
19320 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
19330 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
19340 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
19350 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
19360 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
19370 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
19380 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65   authorized. The
19390 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
193a0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
193b0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
193c0 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
193d0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
193e0 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
193f0 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
19400 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
19410 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
19420 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  zed..**.** An au
19430 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
19440 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
19450 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
19460 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
19470 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
19480 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
19490 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
194a0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
194b0 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
194c0 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
194d0 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
194e0 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
194f0 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
19500 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
19510 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
19520 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
19530 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
19540 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
19550 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
19560 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
19570 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
19580 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
19590 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
195a0 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
195b0 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
195c0 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
195d0 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
195e0 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
195f0 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
19600 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
19610 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
19620 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
19630 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
19640 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
19650 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
19660 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
19670 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
19680 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
19690 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
196a0 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
196b0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
196c0 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
196d0 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
196e0 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
196f0 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
19700 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
19710 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
19720 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
19730 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
19740 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
19750 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
19760 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
19770 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
19780 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
19790 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
197a0 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
197b0 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20  zer..**.** Only 
197c0 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
197d0 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
197e0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
197f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
19800 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
19810 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
19820 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
19830 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
19840 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20   previous call. 
19850 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74   Disable the aut
19860 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
19870 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
19880 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
19890 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
198a0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
198b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
198c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
198d0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
198e0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
198f0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
19900 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19910 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
19920 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19930 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
19940 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
19950 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
19960 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
19970 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
19980 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
19990 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
199a0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
199b0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
199c0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68  agraph..**.** Wh
199d0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
199e0 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
199f0 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
19a00 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
19a10 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
19a20 20 62 65 20 72 65 70 72 65 70 61 72 65 64 20 64   be reprepared d
19a30 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
19a40 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
19a50 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
19a60 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
19a70 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
19a80 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
19a90 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
19aa0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19ab0 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
19ac0 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
19ad0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
19ae0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
19af0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19b00 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
19b10 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
19b20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19b30 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
19b40 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
19b50 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
19b60 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
19b70 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
19b80 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
19b90 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
19ba0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
19bb0 2a 20 7b 48 31 32 35 30 31 7d 20 54 68 65 20 5b  * {H12501} The [
19bc0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
19bd0 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20 69  orizer(D,...)] i
19be0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
19bf0 72 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  rs a.**         
19c00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19c10 62 61 63 6b 20 77 69 74 68 20 64 61 74 61 62 61  back with databa
19c20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
19c30 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 32 7d 20  .**.** {H12502} 
19c40 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
19c50 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
19c60 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
19c70 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20 20 20 20  ents are.**     
19c80 20 20 20 20 20 62 65 69 6e 67 20 70 61 72 73 65       being parse
19c90 65 64 20 61 6e 64 20 63 6f 6d 70 69 6c 65 64 2e  ed and compiled.
19ca0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 33 7d 20  .**.** {H12503} 
19cb0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
19cc0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
19cd0 6e 73 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ns any value oth
19ce0 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
19cf0 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f      [SQLITE_IGNO
19d00 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
19d10 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
19d20 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  Y], then.**     
19d30 20 20 20 20 20 74 68 65 20 61 70 70 6c 69 63 61       the applica
19d40 74 69 6f 6e 20 69 6e 74 65 72 66 61 63 65 20 63  tion interface c
19d50 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 0a  all that caused.
19d60 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
19d70 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19d80 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c  ack to run shall
19d90 20 66 61 69 6c 20 77 69 74 68 20 61 6e 0a 2a 2a   fail with an.**
19da0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
19db0 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63  E_ERROR] error c
19dc0 6f 64 65 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  ode and an appro
19dd0 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
19de0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  sage..**.** {H12
19df0 35 30 34 7d 20 57 68 65 6e 20 74 68 65 20 61 75  504} When the au
19e00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
19e10 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
19e20 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65 72 61  E_OK], the opera
19e30 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
19e40 20 64 65 73 63 72 69 62 65 64 20 69 73 20 70 72   described is pr
19e50 6f 63 65 73 73 65 64 20 6e 6f 72 6d 61 6c 6c 79  ocessed normally
19e60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 35 7d  ..**.** {H12505}
19e70 20 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72   When the author
19e80 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
19e90 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
19ea0 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 20 20 20  NY], the.**     
19eb0 20 20 20 20 20 61 70 70 6c 69 63 61 74 69 6f 6e       application
19ec0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20   interface call 
19ed0 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 0a  that caused the.
19ee0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68  **          auth
19ef0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
19f00 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69  to run shall fai
19f10 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  l.**          wi
19f20 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45 52  th an [SQLITE_ER
19f30 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20  ROR] error code 
19f40 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  and an error mes
19f50 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  sage.**         
19f60 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
19f70 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
19f80 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 36  d..**.** {H12506
19f90 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69  } If the authori
19fa0 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e  zer code (the 2n
19fb0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
19fc0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a  he authorizer.**
19fd0 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
19fe0 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ck) is [SQLITE_R
19ff0 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61 75 74  EAD] and the aut
1a000 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1a010 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
1a020 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e       [SQLITE_IGN
1a030 4f 52 45 5d 2c 20 74 68 65 6e 20 74 68 65 20 70  ORE], then the p
1a040 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1a050 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
1a060 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1a070 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61  insert a NULL va
1a080 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
1a090 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1a0a0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
1a0b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 65  .**          bee
1a0c0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
1a0d0 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
1a0e0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eturned..**.** {
1a0f0 48 31 32 35 30 37 7d 20 49 66 20 74 68 65 20 61  H12507} If the a
1a100 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28  uthorizer code (
1a110 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
1a120 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
1a130 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  zer.**          
1a140 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e 79  callback) is any
1a150 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
1a160 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c 20   [SQLITE_READ], 
1a170 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
1a180 20 61 20 72 65 74 75 72 6e 20 6f 66 20 5b 53 51   a return of [SQ
1a190 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61 73  LITE_IGNORE] has
1a1a0 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63 74   the same effect
1a1b0 20 61 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   as [SQLITE_DENY
1a1c0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 30  ]..**.** {H12510
1a1d0 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
1a1e0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1a1f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1a200 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
1a210 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74 68            the th
1a220 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
1a230 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
1a240 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
1a250 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
1a260 20 7b 48 31 32 35 31 31 7d 20 54 68 65 20 73 65   {H12511} The se
1a270 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1a280 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1a290 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
1a2a0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
1a2b0 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
1a2c0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
1a2d0 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75 6c  ies the particul
1a2e0 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  ar action.**    
1a2f0 20 20 20 20 20 20 74 6f 20 62 65 20 61 75 74 68        to be auth
1a300 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  orized..**.** {H
1a310 31 32 35 31 32 7d 20 54 68 65 20 74 68 69 72 64  12512} The third
1a320 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
1a330 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
1a340 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a 2a   callback are.**
1a350 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
1a360 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1a370 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 0a 2a  s that contain.*
1a380 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 69 74  *          addit
1a390 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62  ional details ab
1a3a0 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
1a3b0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1a3c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 30 7d 20  .**.** {H12520} 
1a3d0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
1a3e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1a3f0 69 7a 65 72 28 29 5d 20 6f 76 65 72 72 69 64 65  izer()] override
1a400 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  s.**          an
1a410 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69 6e 73  y previously ins
1a420 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69 7a 65  talled authorize
1a430 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 31  r..**.** {H12521
1a440 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69  } A NULL authori
1a450 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20 6e  zer means that n
1a460 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  o authorization.
1a470 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
1a480 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
1a490 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 32 7d 20  .**.** {H12522} 
1a4a0 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74 68  The default auth
1a4b0 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e 0a  orizer is NULL..
1a4c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
1a4d0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
1a4e0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
1a4f0 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
1a500 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
1a510 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1a520 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1a530 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
1a540 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
1a550 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1a560 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
1a570 64 65 73 20 7b 48 31 32 35 39 30 7d 20 3c 48 31  des {H12590} <H1
1a580 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2500>.**.** The 
1a590 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1a5a0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1a5b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
1a5c0 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
1a5d0 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
1a5e0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
1a5f0 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
1a600 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
1a610 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
1a620 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
1a630 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
1a640 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
1a650 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
1a660 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1a670 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
1a680 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
1a690 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1a6a0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23  nformation..*/.#
1a6b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1a6c0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
1a6d0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1a6e0 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
1a6f0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1a700 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
1a710 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
1a720 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
1a730 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
1a740 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
1a750 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1a760 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b 48   Action Codes {H
1a770 31 32 35 35 30 7d 20 3c 48 31 32 35 30 30 3e 0a  12550} <H12500>.
1a780 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1a790 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1a7a0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
1a7b0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
1a7c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
1a7d0 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
1a7e0 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
1a7f0 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
1a800 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
1a810 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1a820 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
1a830 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1a840 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
1a850 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
1a860 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
1a870 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
1a880 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
1a890 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
1a8a0 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
1a8b0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1a8c0 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
1a8d0 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
1a8e0 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
1a8f0 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
1a900 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
1a910 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
1a920 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
1a930 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
1a940 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
1a950 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
1a960 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
1a970 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
1a980 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
1a990 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
1a9a0 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
1a9b0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1a9c0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
1a9d0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
1a9e0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1a9f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1aa00 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1aa10 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
1aa20 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
1aa30 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
1aa40 20 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65    The 6th parame
1aa50 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1aa60 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
1aa70 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
1aa80 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
1aa90 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
1aaa0 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
1aab0 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
1aac0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
1aad0 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
1aae0 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
1aaf0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
1ab00 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
1ab10 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ode..**.** INVAR
1ab20 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
1ab30 32 35 35 31 7d 20 54 68 65 20 73 65 63 6f 6e 64  2551} The second
1ab40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 61 6e   parameter to an
1ab50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1ab60 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1ab70 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1ab80 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61 6c  r callback] shal
1ab90 6c 20 62 65 20 61 6e 20 69 6e 74 65 67 65 72 0a  l be an integer.
1aba0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
1abb0 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f  ITE_COPY | autho
1abc0 72 69 7a 65 72 20 63 6f 64 65 5d 20 74 68 61 74  rizer code] that
1abd0 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 20   specifies what 
1abe0 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  action.**       
1abf0 20 20 20 69 73 20 62 65 69 6e 67 20 61 75 74 68     is being auth
1ac00 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  orized..**.** {H
1ac10 31 32 35 35 32 7d 20 54 68 65 20 33 72 64 20 61  12552} The 3rd a
1ac20 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1ac30 73 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  s to the.**     
1ac40 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65       [sqlite3_se
1ac50 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1ac60 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c  uthorization cal
1ac70 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20 20 20 20 20  lback].**       
1ac80 20 20 20 73 68 61 6c 6c 20 62 65 20 70 61 72 61     shall be para
1ac90 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
1aca0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
1acb0 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  h.**          [S
1acc0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74  QLITE_COPY | aut
1acd0 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 69 73  horizer code] is
1ace0 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
1acf0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ond parameter..*
1ad00 2a 0a 2a 2a 20 7b 48 31 32 35 35 33 7d 20 54 68  *.** {H12553} Th
1ad10 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
1ad20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
1ad30 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f     [sqlite3_set_
1ad40 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1ad50 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ad60 5d 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20 6e  ] shall be the n
1ad70 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
1ad80 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1ad90 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69 6e 22  (example: "main"
1ada0 2c 20 22 74 65 6d 70 22 2c 20 65 74 63 2e 29 20  , "temp", etc.) 
1adb0 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 0a 2a  if applicable..*
1adc0 2a 0a 2a 2a 20 7b 48 31 32 35 35 34 7d 20 54 68  *.** {H12554} Th
1add0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
1ade0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
1adf0 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f     [sqlite3_set_
1ae00 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1ae10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ae20 5d 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20 6e  ] shall be the n
1ae30 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
1ae40 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
1ae50 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
1ae60 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
1ae70 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20  sible for.**    
1ae80 20 20 20 20 20 20 74 68 65 20 61 63 63 65 73 73        the access
1ae90 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
1aea0 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
1aeb0 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
1aec0 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20  tly from.**     
1aed0 20 20 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53       top-level S
1aee0 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
1aef0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1af00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1af10 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
1af20 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
1af30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
1af40 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1af50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1af60 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
1af70 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1af80 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1af90 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1afa0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1afb0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1afc0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1afd0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1afe0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1aff0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
1b000 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1b010 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1b020 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b030 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1b040 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
1b050 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b060 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b070 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b080 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1b090 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
1b0a0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1b0b0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1b0c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b0d0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1b0e0 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
1b0f0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1b100 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b110 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b120 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
1b130 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
1b140 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1b150 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b160 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b170 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
1b180 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
1b190 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1b1a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b1b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b1c0 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
1b1d0 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
1b1e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1b1f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b200 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b210 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
1b220 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
1b230 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1b240 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1b250 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b260 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
1b270 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
1b280 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1b290 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b2a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b2b0 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
1b2c0 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
1b2d0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1b2e0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1b2f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1b300 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
1b310 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
1b320 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1b330 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1b340 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1b350 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
1b360 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
1b370 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1b380 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1b390 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1b3a0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1b3b0 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
1b3c0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1b3d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b3e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1b3f0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
1b400 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
1b410 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1b420 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1b430 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1b440 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
1b450 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
1b460 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1b470 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b480 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
1b490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
1b4a0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b4b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b4c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b4d0 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
1b4e0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
1b4f0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
1b500 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
1b510 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
1b520 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
1b530 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
1b540 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b550 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1b560 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b570 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
1b580 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
1b590 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1b5a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b5b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b5c0 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
1b5d0 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
1b5e0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1b5f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b600 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b610 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
1b620 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
1b630 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b640 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1b650 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b660 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
1b670 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
1b680 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
1b690 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b6a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b6b0 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
1b6c0 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
1b6d0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
1b6e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b6f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b700 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
1b710 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
1b720 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
1b730 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1b740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b750 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
1b760 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
1b770 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
1b780 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b790 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1b7a0 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
1b7b0 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
1b7c0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1b7d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b7e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1b7f0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
1b800 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
1b810 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1b820 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1b830 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1b840 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
1b850 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
1b860 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1b870 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1b880 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
1b890 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
1b8a0 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
1b8b0 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
1b8c0 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
1b8d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
1b8e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b8f0 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
1b900 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  r used */../*.**
1b910 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
1b920 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
1b930 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 32 32   Functions {H122
1b940 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 20  80} <S60400>.** 
1b950 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
1b960 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1b970 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
1b980 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
1b990 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
1b9a0 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
1b9b0 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
1b9c0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
1b9d0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1b9e0 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
1b9f0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1ba00 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
1ba10 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
1ba20 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
1ba30 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
1ba40 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
1ba50 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
1ba60 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1ba70 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   The callback re
1ba80 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72 65  turns a UTF-8 re
1ba90 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 53  ndering of the S
1baa0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1bab0 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61 74  t.** as the stat
1bac0 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
1bad0 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20 41  ns executing.  A
1bae0 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61  dditional callba
1baf0 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  cks occur.** as 
1bb00 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
1bb10 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
1bb20 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
1bb30 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
1bb40 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
1bb50 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
1bb60 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
1bb70 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a   the trigger..**
1bb80 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
1bb90 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1bba0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1bbb0 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
1bbc0 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
1bbd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
1bbe0 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70 72 6f  nishes.  The pro
1bbf0 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
1bc00 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
1bc10 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
1bc20 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
1bc30 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
1bc40 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
1bc50 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
1bc60 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
1bc70 75 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  un..**.** INVARI
1bc80 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
1bc90 32 38 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63  281} The callbac
1bca0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1bcb0 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65  tered by [sqlite
1bcc0 33 5f 74 72 61 63 65 28 29 5d 20 0a 2a 2a 20 20  3_trace()] .**  
1bcd0 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 62 65          shall be
1bce0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20   invoked.**     
1bcf0 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 6e       whenever an
1bd00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
1bd10 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 65  irst begins to e
1bd20 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20  xecute and.**   
1bd30 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20         whenever 
1bd40 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f  a trigger subpro
1bd50 67 72 61 6d 20 66 69 72 73 74 20 62 65 67 69 6e  gram first begin
1bd60 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  s to run..**.** 
1bd70 7b 48 31 32 32 38 32 7d 20 45 61 63 68 20 63 61  {H12282} Each ca
1bd80 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  ll to [sqlite3_t
1bd90 72 61 63 65 28 29 5d 20 73 68 61 6c 6c 20 6f 76  race()] shall ov
1bda0 65 72 72 69 64 65 20 74 68 65 20 70 72 65 76 69  erride the previ
1bdb0 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ously.**        
1bdc0 20 20 72 65 67 69 73 74 65 72 65 64 20 74 72 61    registered tra
1bdd0 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ce callback..**.
1bde0 2a 2a 20 7b 48 31 32 32 38 33 7d 20 41 20 4e 55  ** {H12283} A NU
1bdf0 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  LL trace callbac
1be00 6b 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20  k shall disable 
1be10 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  tracing..**.** {
1be20 48 31 32 32 38 34 7d 20 54 68 65 20 66 69 72 73  H12284} The firs
1be30 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
1be40 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
1be50 20 73 68 61 6c 6c 20 62 65 20 61 20 63 6f 70 79   shall be a copy
1be60 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
1be70 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68 69 63  the pointer whic
1be80 68 20 77 61 73 20 74 68 65 20 33 72 64 20 61 72  h was the 3rd ar
1be90 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
1bea0 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a  e3_trace()]..**.
1beb0 2a 2a 20 7b 48 31 32 32 38 35 7d 20 54 68 65 20  ** {H12285} The 
1bec0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
1bed0 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  to the trace cal
1bee0 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20  lback is a.**   
1bef0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
1bf00 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
1bf10 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
1bf20 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65 78 74  he original text
1bf30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
1bf40 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1bf50 74 20 61 73 20 69 74 20 77 61 73 20 70 61 73 73  t as it was pass
1bf60 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33  ed into [sqlite3
1bf70 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a  _prepare_v2()].*
1bf80 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
1bf90 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72  e equivalent, or
1bfa0 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20   an SQL comment 
1bfb0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 62  indicating the b
1bfc0 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20  eginning.**     
1bfd0 20 20 20 20 20 6f 66 20 61 20 74 72 69 67 67 65       of a trigge
1bfe0 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a  r subprogram..**
1bff0 0a 2a 2a 20 7b 48 31 32 32 38 37 7d 20 54 68 65  .** {H12287} The
1c000 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1c010 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1c020 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
1c030 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a  e()] is invoked.
1c040 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 65  **          as e
1c050 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
1c060 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a  t finishes..**.*
1c070 2a 20 7b 48 31 32 32 38 38 7d 20 54 68 65 20 66  * {H12288} The f
1c080 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1c090 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61  o the profile ca
1c0a0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
1c0b0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
1c0c0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
1c0d0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  r to [sqlite3_pr
1c0e0 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ofile()]..**.** 
1c0f0 7b 48 31 32 32 38 39 7d 20 54 68 65 20 73 65 63  {H12289} The sec
1c100 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1c110 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c   the profile cal
1c120 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20  lback is a.**   
1c130 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
1c140 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
1c150 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ing that contain
1c160 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74  s the complete t
1c170 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ext of.**       
1c180 20 20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65     the SQL state
1c190 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70  ment as it was p
1c1a0 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73 71 6c  rocessed by [sql
1c1b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1c1c0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
1c1d0 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
1c1e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 39 30 7d  ..**.** {H12290}
1c1f0 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
1c200 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66  eter to the prof
1c210 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ile callback is 
1c220 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20  an estimate.**  
1c230 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6e          of the n
1c240 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63  umber of nanosec
1c250 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  onds of wall-clo
1c260 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72 65 64  ck time required
1c270 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1c280 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  run the SQL stat
1c290 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61 72 74  ement from start
1c2a0 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 53   to finish..*/.S
1c2b0 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
1c2c0 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
1c2d0 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
1c2e0 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
1c2f0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1c300 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
1c310 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
1c320 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
1c330 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
1c340 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
1c350 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
1c360 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
1c370 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
1c380 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
1c390 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
1c3a0 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30 7d 20  lbacks {H12910} 
1c3b0 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60400>.**.** T
1c3c0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66  his routine conf
1c3d0 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63  igures a callbac
1c3e0 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65  k function - the
1c3f0 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c  .** progress cal
1c400 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20  lback - that is 
1c410 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
1c420 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
1c430 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  .** running call
1c440 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  s to [sqlite3_ex
1c450 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
1c460 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  step()] and.** [
1c470 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1c480 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c  e()].  An exampl
1c490 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
1c4a0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
1c4b0 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
1c4c0 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
1c4d0 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
1c4e0 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73   If the progress
1c4f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1c500 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
1c510 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
1c520 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
1c530 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
1c540 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
1c550 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
1c560 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
1c570 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
1c580 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
1c590 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1c5a0 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  r must not do an
1c5b0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1c5c0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1c5d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c5e0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1c5f0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1c600 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
1c610 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1c620 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1c630 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1c640 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1c650 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1c660 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1c670 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1c680 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1c690 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 49 4e  agraph..**.** IN
1c6a0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1c6b0 7b 48 31 32 39 31 31 7d 20 54 68 65 20 63 61 6c  {H12911} The cal
1c6c0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1c6d0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
1c6e0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1c6f0 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20  ndler().**      
1c700 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 70      is invoked p
1c710 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
1c720 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
1c730 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20  calls to.**     
1c740 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74       [sqlite3_st
1c750 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ep()]..**.** {H1
1c760 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67 72 65  2912} The progre
1c770 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ss callback is i
1c780 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
1c790 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c 0a  every N virtual.
1c7a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61 63 68  **          mach
1c7b0 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65  ine opcodes, whe
1c7c0 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
1c7d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
1c7e0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
1c7f0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1c800 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c  _handler()] call
1c810 20 74 68 61 74 20 72 65 67 69 73 74 65 72 65 64   that registered
1c820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1c830 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 4e   callback.  If N
1c840 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 2c   is less than 1,
1c850 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1c860 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20  s_handler().**  
1c870 20 20 20 20 20 20 20 20 61 63 74 73 20 61 73 20          acts as 
1c880 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67 72 65  if a NULL progre
1c890 73 73 20 68 61 6e 64 6c 65 72 20 68 61 64 20 62  ss handler had b
1c8a0 65 65 6e 20 73 70 65 63 69 66 69 65 64 2e 0a 2a  een specified..*
1c8b0 2a 0a 2a 2a 20 7b 48 31 32 39 31 33 7d 20 54 68  *.** {H12913} Th
1c8c0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
1c8d0 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20 69 64  ack itself is id
1c8e0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
1c8f0 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 20 20  third.**        
1c900 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71    argument to sq
1c910 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1c920 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a 2a 20  andler()..**.** 
1c930 7b 48 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75  {H12914} The fou
1c940 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
1c950 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1c960 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20 61 0a  _handler() is a.
1c970 2a 2a 20 20 20 20 20 20 20 20 20 20 76 6f 69 64  **          void
1c980 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
1c990 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  to the progress 
1c9a0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
1c9b0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 65 61       function ea
1c9c0 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e  ch time it is in
1c9d0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  voked..**.** {H1
1c9e0 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c 6c 20  2915} If a call 
1c9f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
1ca00 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e 20 66  ()] results in f
1ca10 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f  ewer than N opco
1ca20 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  des.**          
1ca30 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c 20  being executed, 
1ca40 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73  then the progres
1ca50 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65  s callback is ne
1ca60 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a  ver invoked..**.
1ca70 2a 2a 20 7b 48 31 32 39 31 36 7d 20 45 76 65 72  ** {H12916} Ever
1ca80 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  y call to [sqlit
1ca90 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1caa0 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ler()].**       
1cab0 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e     overwrites an
1cac0 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  y previously reg
1cad0 69 73 74 65 72 65 64 20 70 72 6f 67 72 65 73 73  istered progress
1cae0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
1caf0 7b 48 31 32 39 31 37 7d 20 49 66 20 74 68 65 20  {H12917} If the 
1cb00 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1cb10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1cb20 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65  L then no progre
1cb30 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  ss.**          h
1cb40 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65  andler is invoke
1cb50 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 38  d..**.** {H12918
1cb60 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73  } If the progres
1cb70 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
1cb80 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65  ns a result othe
1cb90 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a  r than 0, then.*
1cba0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
1cbb0 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 66 20  ehavior is a if 
1cbc0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
1cbd0 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63  pt()] had been c
1cbe0 61 6c 6c 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20  alled..**       
1cbf0 20 20 20 3c 53 33 30 35 30 30 3e 0a 2a 2f 0a 76     <S30500>.*/.v
1cc00 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
1cc10 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
1cc20 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
1cc30 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
1cc40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cc50 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
1cc60 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
1cc70 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c  ction {H12700} <
1cc80 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40200>.**.** Th
1cc90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
1cca0 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
1ccb0 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20  base file whose 
1ccc0 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79  name is given by
1ccd0 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
1cce0 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 66   argument. The f
1ccf0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1cd00 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1cd10 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
1cd20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1cd30 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1cd40 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
1cd50 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1cd60 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
1cd70 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
1cd80 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61 73 65  6(). A [database
1cd90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1cda0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
1cdb0 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
1cdc0 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
1cdd0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
1cde0 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
1cdf0 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
1ce00 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
1ce10 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
1ce20 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1ce30 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1ce40 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
1ce50 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
1ce60 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
1ce70 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
1ce80 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
1ce90 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65 20 64  object. If the d
1cea0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1ceb0 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
1cec0 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
1ced0 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
1cee0 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
1cef0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
1cf00 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1cf10 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a  returned.  The.*
1cf20 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1cf30 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
1cf40 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
1cf50 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
1cf60 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
1cf70 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
1cf80 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
1cf90 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a  f the error..**.
1cfa0 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 65  ** The default e
1cfb0 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
1cfc0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1cfd0 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
1cfe0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1cff0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1d000 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
1d010 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
1d020 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1d030 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
1d040 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
1d050 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
1d060 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
1d070 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
1d080 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
1d090 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1d0a0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
1d0b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1d0c0 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
1d0d0 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
1d0e0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
1d0f0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
1d100 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
1d110 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
1d120 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
1d130 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
1d140 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
1d150 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
1d160 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1d170 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
1d180 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
1d190 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
1d1a0 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
1d1b0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1d1c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
1d1d0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
1d1e0 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  r can take one o
1d1f0 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
1d200 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
1d210 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1d220 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
1d230 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
1d240 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49  OMUTEX] or [SQLI
1d250 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1d260 58 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a 20  X] flags:.**.** 
1d270 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c  <dl>.** <dt>[SQL
1d280 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1d290 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
1d2a0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1d2b0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
1d2c0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
1d2d0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1d2e0 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
1d2f0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1d300 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a   returned.</dd>.
1d310 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54  **.** <dt>[SQLIT
1d320 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1d330 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1d340 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1d350 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1d360 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
1d370 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
1d380 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
1d390 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
1d3a0 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
1d3b0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1d3c0 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
1d3d0 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
1d3e0 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
1d3f0 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
1d400 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
1d410 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  eturned.</dd>.**
1d420 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  .** <dt>[SQLITE_
1d430 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
1d440 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
1d450 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
1d460 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1d470 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1d480 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1d490 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
1d4a0 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f  s it if.** it do
1d4b0 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
1d4c0 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
1d4d0 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
1d4e0 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
1d4f0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
1d500 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1d510 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a  _open16().</dd>.
1d520 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
1d530 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
1d540 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1d550 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
1d560 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
1d570 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
1d580 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66   above or one of
1d590 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e   the combination
1d5a0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f  s shown above co
1d5b0 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74  mbined.** with t
1d5c0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1d5d0 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c  NOMUTEX] or [SQL
1d5e0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
1d5f0 45 58 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68  EX] flags,.** th
1d600 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1d610 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
1d620 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c 49  .** If the [SQLI
1d630 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1d640 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
1d650 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1d660 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
1d670 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
1d680 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
1d690 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
1d6a0 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
1d6b0 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
1d6c0 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
1d6d0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
1d6e0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 49  r start-time.  I
1d6f0 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
1d700 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
1d710 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
1d720 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
1d730 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
1d740 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
1d750 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
1d760 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
1d770 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
1d780 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
1d790 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
1d7a0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
1d7b0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ime..**.** If th
1d7c0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
1d7d0 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
1d7e0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1d7f0 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
1d800 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
1d810 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
1d820 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69  nection.  This i
1d830 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1d840 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
1d850 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
1d860 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1d870 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
1d880 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1d890 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
1d8a0 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
1d8b0 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
1d8c0 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
1d8d0 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
1d8e0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
1d8f0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
1d900 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
1d910 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
1d920 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
1d930 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
1d940 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
1d950 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
1d960 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
1d970 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
1d980 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
1d990 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
1d9a0 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
1d9b0 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
1d9c0 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
1d9d0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
1d9e0 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
1d9f0 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
1da00 65 64 2e 20 20 54 68 69 73 20 70 72 69 76 61 74  ed.  This privat
1da10 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1da20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
1da30 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
1da40 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
1da50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1da60 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
1da70 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
1da80 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1da90 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
1daa0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
1dab0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1dac0 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
1dad0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
1dae0 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
1daf0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
1db00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1db10 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
1db20 20 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20    If the fourth 
1db30 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1db40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1db50 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
1db60 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1db70 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
1db80 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
1db90 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
1dba0 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
1dbb0 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
1dbc0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
1dbd0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
1dbe0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1dbf0 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
1dc00 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
1dc10 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
1dc20 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
1dc30 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
1dc40 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
1dc50 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
1dc60 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
1dc70 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
1dc80 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
1dc90 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
1dca0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1dcb0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
1dcc0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e  n_v2()..**.** IN
1dcd0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1dce0 7b 48 31 32 37 30 31 7d 20 54 68 65 20 5b 73 71  {H12701} The [sq
1dcf0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1dd00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1dd10 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ], and.**       
1dd20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
1dd30 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
1dd40 73 20 63 72 65 61 74 65 20 61 20 6e 65 77 0a 2a  s create a new.*
1dd50 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
1dd60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1dd70 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1dd80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1dd90 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 67   database file g
1dda0 69 76 65 6e 20 69 6e 20 74 68 65 69 72 20 66 69  iven in their fi
1ddb0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
1ddc0 2a 0a 2a 2a 20 7b 48 31 32 37 30 32 7d 20 54 68  *.** {H12702} Th
1ddd0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1dde0 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
1ddf0 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20  ed as UTF-8.**  
1de00 20 20 20 20 20 20 20 20 66 6f 72 20 5b 73 71 6c          for [sql
1de10 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  ite3_open()] and
1de20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1de30 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d  2()] and as UTF-
1de40 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  16.**          i
1de50 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1de60 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c  e order for [sql
1de70 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
1de80 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 33 7d 20 41  **.** {H12703} A
1de90 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
1dea0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1deb0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1dec0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a  ite3_open16()],.
1ded0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
1dee0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1def0 29 5d 20 77 72 69 74 65 73 20 61 20 70 6f 69 6e  )] writes a poin
1df00 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20  ter to a new.** 
1df10 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
1df20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
1df30 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a  nto *ppDb..**.**
1df40 20 7b 48 31 32 37 30 34 7d 20 54 68 65 20 5b 73   {H12704} The [s
1df50 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
1df60 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
1df70 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  )], and.**      
1df80 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
1df90 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
1dfa0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1dfb0 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65  E_OK] upon succe
1dfc0 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss,.**          
1dfd0 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
1dfe0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
1dff0 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  n failure..**.**
1e000 20 7b 48 31 32 37 30 36 7d 20 54 68 65 20 64 65   {H12706} The de
1e010 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64  fault text encod
1e020 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61  ing for a new da
1e030 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75  tabase created u
1e040 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
1e050 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1e060 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
1e070 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62 65  en_v2()] will be
1e080 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48   UTF-8..**.** {H
1e090 31 32 37 30 37 7d 20 54 68 65 20 64 65 66 61 75  12707} The defau
1e0a0 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  lt text encoding
1e0b0 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62   for a new datab
1e0c0 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  ase created usin
1e0d0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
1e0e0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1e0f0 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e   will be UTF-16.
1e100 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 39 7d 20  .**.** {H12709} 
1e110 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
1e120 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  n(F,D)] interfac
1e130 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  e is equivalent 
1e140 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
1e150 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1e160 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72 65 20  F,D,G,0)] where 
1e170 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
1e180 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  is.**          [
1e190 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1e1a0 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f  WRITE]|[SQLITE_O
1e1b0 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a  PEN_CREATE]..**.
1e1c0 2a 2a 20 7b 48 31 32 37 31 31 7d 20 49 66 20 74  ** {H12711} If t
1e1d0 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74  he G parameter t
1e1e0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
1e1f0 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e  v2(F,D,G,V)] con
1e200 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  tains the.**    
1e210 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20        bit value 
1e220 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1e230 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65 20  DONLY] then the 
1e240 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1e250 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ed.**          f
1e260 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e  or reading only.
1e270 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 32 7d 20  .**.** {H12712} 
1e280 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  If the G paramet
1e290 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  er to [sqlite3_o
1e2a0 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen_v2(F,D,G,V)]
1e2b0 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a   contains the.**
1e2c0 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61            bit va
1e2d0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  lue [SQLITE_OPEN
1e2e0 5f 52 45 41 44 57 52 49 54 45 5d 20 74 68 65 6e  _READWRITE] then
1e2f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1e300 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20   opened.**      
1e310 20 20 20 20 72 65 61 64 69 6e 67 20 61 6e 64 20      reading and 
1e320 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
1e330 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65 61 64  ble, or for read
1e340 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a  ing only if the.
1e350 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
1e360 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
1e370 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
1e380 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a  ting system..**.
1e390 2a 2a 20 7b 48 31 32 37 31 33 7d 20 49 66 20 74  ** {H12713} If t
1e3a0 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74  he G parameter t
1e3b0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
1e3c0 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69  v2(F,D,G,V)] omi
1e3d0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
1e3e0 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
1e3f0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1e400 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  ] and the databa
1e410 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  se does not.**  
1e420 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73          previous
1e430 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  ly exist, an err
1e440 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  or is returned..
1e450 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 34 7d 20 49  **.** {H12714} I
1e460 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
1e470 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
1e480 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en_v2(F,D,G,V)] 
1e490 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20  contains the.** 
1e4a0 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
1e4b0 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
1e4c0 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20  CREATE] and the 
1e4d0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
1e4e0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  t.**          pr
1e4f0 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20  eviously exist, 
1e500 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 20  then an attempt 
1e510 69 73 20 6d 61 64 65 20 74 6f 20 63 72 65 61 74  is made to creat
1e520 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  e and.**        
1e530 20 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65    initialize the
1e540 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a   database..**.**
1e550 20 7b 48 31 32 37 31 37 7d 20 49 66 20 74 68 65   {H12717} If the
1e560 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1e570 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
1e580 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1e590 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20  _open16()],.**  
1e5a0 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
1e5b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
1e5c0 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
1e5d0 65 6e 20 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a  en an private,.*
1e5e0 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d  *          ephem
1e5f0 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20  eral, in-memory 
1e600 64 61 74 61 62 61 73 65 20 69 73 20 63 72 65 61  database is crea
1e610 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
1e620 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20  ection..**      
1e630 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c      <todo>Is SQL
1e640 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c  ITE_OPEN_CREATE|
1e650 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1e660 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a  WRITE required.*
1e670 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71  *          in sq
1e680 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f  lite3_open_v2()?
1e690 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48  </todo>.**.** {H
1e6a0 31 32 37 31 39 7d 20 49 66 20 74 68 65 20 66 69  12719} If the fi
1e6b0 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f  lename is NULL o
1e6c0 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
1e6d0 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
1e6e0 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  e,.**          e
1e6f0 70 68 65 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b  phemeral on-disk
1e700 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1e710 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20  e created..**   
1e720 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20         <todo>Is 
1e730 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1e740 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  TE|SQLITE_OPEN_R
1e750 45 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65  EADWRITE require
1e760 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  d.**          in
1e770 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1e780 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  ()?</todo>.**.**
1e790 20 7b 48 31 32 37 32 31 7d 20 54 68 65 20 5b 64   {H12721} The [d
1e7a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e7b0 6f 6e 5d 20 63 72 65 61 74 65 64 20 62 79 20 5b  on] created by [
1e7c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1e7d0 46 2c 44 2c 47 2c 56 29 5d 0a 2a 2a 20 20 20 20  F,D,G,V)].**    
1e7e0 20 20 20 20 20 20 77 69 6c 6c 20 75 73 65 20 74        will use t
1e7f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1e800 20 6f 62 6a 65 63 74 20 69 64 65 6e 74 69 66 69   object identifi
1e810 65 64 20 62 79 20 74 68 65 20 56 20 70 61 72 61  ed by the V para
1e820 6d 65 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20  meter,.**       
1e830 20 20 20 6f 72 20 74 68 65 20 64 65 66 61 75 6c     or the defaul
1e840 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1e850 6f 62 6a 65 63 74 20 69 66 20 56 20 69 73 20 61  object if V is a
1e860 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1e870 2a 0a 2a 2a 20 7b 48 31 32 37 32 33 7d 20 54 77  *.** {H12723} Tw
1e880 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
1e890 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20 73 68  ections] will sh
1e8a0 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63  are a common cac
1e8b0 68 65 20 69 66 20 62 6f 74 68 20 77 65 72 65 0a  he if both were.
1e8c0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65 6e  **          open
1e8d0 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
1e8e0 20 56 46 53 20 77 68 69 6c 65 20 5b 73 68 61 72   VFS while [shar
1e8f0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 77  ed cache mode] w
1e900 61 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 0a 2a  as enabled and.*
1e910 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 62 6f  *          if bo
1e920 74 68 20 66 69 6c 65 6e 61 6d 65 73 20 63 6f 6d  th filenames com
1e930 70 61 72 65 20 65 71 75 61 6c 20 75 73 69 6e 67  pare equal using
1e940 20 6d 65 6d 63 6d 70 28 29 20 61 66 74 65 72 20   memcmp() after 
1e950 68 61 76 69 6e 67 20 62 65 65 6e 0a 2a 2a 20 20  having been.**  
1e960 20 20 20 20 20 20 20 20 70 72 6f 63 65 73 73 65          processe
1e970 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
1e980 33 5f 76 66 73 20 7c 20 78 46 75 6c 6c 50 61 74  3_vfs | xFullPat
1e990 68 6e 61 6d 65 5d 20 6d 65 74 68 6f 64 20 6f 66  hname] method of
1e9a0 20 74 68 65 20 56 46 53 2e 0a 2a 2f 0a 69 6e 74   the VFS..*/.int
1e9b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
1e9c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
1e9d0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1e9e0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1e9f0 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
1ea00 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
1ea10 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1ea20 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
1ea30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
1ea40 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
1ea50 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
1ea60 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1ea70 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
1ea80 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1ea90 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
1eaa0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1eab0 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
1eac0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
1ead0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
1eae0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1eaf0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1eb00 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
1eb10 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
1eb20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1eb30 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
1eb40 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
1eb50 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
1eb60 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
1eb70 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
1eb80 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
1eb90 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
1eba0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ebb0 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
1ebc0 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 48 31 32  nd Messages {H12
1ebd0 38 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a  800} <S60200>.**
1ebe0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1ebf0 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
1ec00 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1ec10 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
1ec20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
1ec30 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1ec40 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
1ec50 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
1ec60 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
1ec70 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1ec80 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1ec90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
1eca0 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
1ecb0 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
1ecc0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
1ecd0 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
1ece0 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
1ecf0 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
1ed00 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
1ed10 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 54 68 65   undefined.  The
1ed20 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1ed30 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
1ed40 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
1ed50 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
1ed60 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
1ed70 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
1ed80 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
1ed90 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
1eda0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
1edb0 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
1edc0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1edd0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
1ede0 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
1edf0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
1ee00 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
1ee10 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
1ee20 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
1ee30 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
1ee40 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
1ee50 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  ively..** Memory
1ee60 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
1ee70 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
1ee80 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
1ee90 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
1eea0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
1eeb0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
1eec0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
1eed0 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
1eee0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
1eef0 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
1ef00 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
1ef10 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
1ef20 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
1ef30 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
1ef40 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
1ef50 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
1ef60 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
1ef70 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
1ef80 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
1ef90 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
1efa0 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
1efb0 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
1efc0 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
1efd0 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
1efe0 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
1eff0 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
1f000 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
1f010 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
1f020 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
1f030 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
1f040 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
1f050 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
1f060 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
1f070 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
1f080 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
1f090 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
1f0a0 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
1f0b0 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
1f0c0 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
1f0d0 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
1f0e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1f0f0 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
1f100 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
1f110 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
1f120 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
1f130 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
1f140 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
1f150 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
1f160 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
1f170 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
1f180 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
1f190 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
1f1a0 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
1f1b0 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
1f1c0 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
1f1d0 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
1f1e0 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
1f1f0 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
1f200 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
1f210 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
1f220 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
1f230 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
1f240 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
1f250 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
1f260 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
1f270 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
1f280 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1f290 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30  TS:.**.** {H1280
1f2a0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1f2b0 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e 74 65  errcode(D)] inte
1f2c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1f2d0 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20  e numeric.**    
1f2e0 20 20 20 20 20 20 5b 72 65 73 75 6c 74 20 63 6f        [result co
1f2f0 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  de] or [extended
1f300 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
1f310 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
1f320 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tly.**          
1f330 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65  failed interface
1f340 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
1f350 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
1f360 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1f370 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 32  D..**.** {H12802
1f380 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
1f390 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
1f3a0 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  D)] interface re
1f3b0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1f3c0 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65  c.**          [e
1f3d0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1f3e0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1f3f0 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20 20  t recently.**   
1f400 20 20 20 20 20 20 20 66 61 69 6c 65 64 20 69 6e         failed in
1f410 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73  terface call ass
1f420 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
1f430 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1f440 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
1f450 7b 48 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71  {H12803} The [sq
1f460 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d  lite3_errmsg(D)]
1f470 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
1f480 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20  rmsg16(D)].**   
1f490 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
1f4a0 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  s return English
1f4b0 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20 74  -language text t
1f4c0 68 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a  hat describes.**
1f4d0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 65 72            the er
1f4e0 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c  ror in the mostl
1f4f0 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65  y recently faile
1f500 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  d interface call
1f510 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e  ,.**          en
1f520 63 6f 64 65 64 20 61 73 20 65 69 74 68 65 72 20  coded as either 
1f530 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
1f540 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
1f550 0a 2a 2a 20 7b 48 31 32 38 30 37 7d 20 54 68 65  .** {H12807} The
1f560 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
1f570 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72  d by [sqlite3_er
1f580 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c  rmsg()] and [sql
1f590 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
1f5a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
1f5b0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
1f5c0 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69 6e 74   next SQLite int
1f5d0 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a  erface call..**.
1f5e0 2a 2a 20 7b 48 31 32 38 30 38 7d 20 43 61 6c 6c  ** {H12808} Call
1f5f0 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65  s to API routine
1f600 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65  s that do not re
1f610 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f  turn an error co
1f620 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28  de.**          (
1f630 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65  example: [sqlite
1f640 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29  3_data_count()])
1f650 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20   do not.**      
1f660 20 20 20 20 63 68 61 6e 67 65 20 74 68 65 20 65      change the e
1f670 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65 73  rror code or mes
1f680 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 62 79  sage returned by
1f690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1f6a0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1f6b0 2c 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  , [sqlite3_exten
1f6c0 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a  ded_errcode()],.
1f6d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1f6e0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20  ite3_errmsg()], 
1f6f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
1f700 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  sg16()]..**.** {
1f710 48 31 32 38 30 39 7d 20 49 6e 74 65 72 66 61 63  H12809} Interfac
1f720 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f 74 20  es that are not 
1f730 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1f740 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 20 20  a specific.**   
1f750 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
1f760 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 65 78   connection] (ex
1f770 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20 20 20  amples:.**      
1f780 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72      [sqlite3_mpr
1f790 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69  intf()] or [sqli
1f7a0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
1f7b0 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20 20 20  d_cache()].**   
1f7c0 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20 63 68         do not ch
1f7d0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 20  ange the values 
1f7e0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
1f7f0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1f800 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71  _errcode()], [sq
1f810 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
1f820 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20  rrcode()],.**   
1f830 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1f840 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73  errmsg()], or [s
1f850 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1f860 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1f870 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
1f880 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c  e3 *db);.int sql
1f890 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
1f8a0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1f8b0 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
1f8c0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
1f8d0 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
1f8e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
1f8f0 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
1f900 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f910 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
1f920 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30 30 7d   Object {H13000}
1f930 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59   <H13010>.** KEY
1f940 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
1f950 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
1f960 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1f970 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
1f980 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
1f990 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
1f9a0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
1f9b0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
1f9c0 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
1f9d0 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
1f9e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f9f0 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
1fa00 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
1fa10 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
1fa20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
1fa30 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
1fa40 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
1fa50 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
1fa60 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
1fa70 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
1fa80 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
1fa90 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1faa0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1fab0 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
1fac0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
1fad0 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
1fae0 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
1faf0 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
1fb00 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1fb10 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
1fb20 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
1fb30 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
1fb40 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
1fb50 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
1fb60 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
1fb70 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
1fb80 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1fb90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
1fba0 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
1fbb0 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
1fbc0 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
1fbd0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
1fbe0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
1fbf0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
1fc00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1fc10 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
1fc20 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
1fc30 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
1fc40 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
1fc50 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
1fc60 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1fc70 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
1fc80 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
1fc90 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
1fca0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1fcb0 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
1fcc0 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30 36 30   {H12760} <S2060
1fcd0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0>.**.** This in
1fce0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
1fcf0 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
1fd00 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
1fd10 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
1fd20 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
1fd30 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
1fd40 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
1fd50 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
1fd60 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1fd70 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
1fd80 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
1fd90 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
1fda0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1fdb0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
1fdc0 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
1fdd0 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
1fde0 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
1fdf0 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
1fe00 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
1fe10 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
1fe20 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1fe30 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
1fe40 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54  at construct.  T
1fe50 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
1fe60 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69  rns the old limi
1fe70 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
1fe80 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
1fe90 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
1fea0 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
1feb0 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74  hanged..** For t
1fec0 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  he limit categor
1fed0 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49  y of SQLITE_LIMI
1fee0 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61  T_XYZ there is a
1fef0 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 62   hard upper.** b
1ff00 6f 75 6e 64 20 73 65 74 20 62 79 20 61 20 63 6f  ound set by a co
1ff10 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65  mpile-time C pre
1ff20 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
1ff30 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d 41 58  named SQLITE_MAX
1ff40 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  _XYZ..** (The "_
1ff50 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
1ff60 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
1ff70 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41  o "_MAX_".).** A
1ff80 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
1ff90 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
1ffa0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
1ffb0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
1ffc0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
1ffd0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
1ffe0 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20  er limit..**.** 
1fff0 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run time limits 
20000 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
20010 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
20020 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
20030 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
20040 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
20050 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
20060 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
20070 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
20080 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
20090 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
200a0 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
200b0 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
200c0 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65 72 20 74  .** webbrowser t
200d0 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
200e0 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
200f0 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
20100 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
20110 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
20120 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
20130 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
20140 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
20150 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
20160 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
20170 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
20180 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
20190 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
201a0 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
201b0 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
201c0 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
201d0 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
201e0 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
201f0 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
20200 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
20210 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
20220 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
20230 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
20240 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
20250 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
20260 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
20270 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
20280 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
20290 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
202a0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
202b0 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
202c0 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
202d0 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
202e0 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
202f0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
20300 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
20310 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
20320 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
20330 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
20340 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
20350 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
20360 2a 20 7b 48 31 32 37 36 32 7d 20 41 20 73 75 63  * {H12762} A suc
20370 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
20380 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
20390 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69  ,C,V)] where V i
203a0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  s.**          po
203b0 73 69 74 69 76 65 20 63 68 61 6e 67 65 73 20 74  sitive changes t
203c0 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  he limit on the 
203d0 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63  size of construc
203e0 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  t C in the.**   
203f0 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
20400 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74   connection] D t
20410 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20  o the lesser of 
20420 56 20 61 6e 64 20 74 68 65 20 68 61 72 64 20 75  V and the hard u
20430 70 70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  pper.**         
20440 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69   bound on the si
20450 7a 65 20 6f 66 20 43 20 74 68 61 74 20 69 73 20  ze of C that is 
20460 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
20470 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ime..**.** {H127
20480 36 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  66} A successful
20490 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
204a0 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20  3_limit(D,C,V)] 
204b0 77 68 65 72 65 20 56 20 69 73 20 6e 65 67 61 74  where V is negat
204c0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
204d0 6c 65 61 76 65 73 20 74 68 65 20 73 74 61 74 65  leaves the state
204e0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
204f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
20500 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  unchanged..**.**
20510 20 7b 48 31 32 37 36 39 7d 20 41 20 73 75 63 63   {H12769} A succ
20520 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
20530 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c  sqlite3_limit(D,
20540 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74 68  C,V)] returns th
20550 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  e.**          va
20560 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
20570 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20   on the size of 
20580 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 74  construct C in t
20590 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
205a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
205b0 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 61 73  ion] D as it was
205c0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61   prior to the ca
205d0 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ll..*/.int sqlit
205e0 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
205f0 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
20600 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
20610 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
20620 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
20630 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48 31 32  es {H12790} <H12
20640 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  760>.** KEYWORDS
20650 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
20660 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  y} {limit catego
20670 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
20680 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
20690 6e 65 20 76 61 72 69 6f 75 73 20 61 73 70 65 63  ne various aspec
206a0 74 73 20 6f 66 20 61 20 5b 64 61 74 61 62 61 73  ts of a [databas
206b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
206c0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 69 6d   that can be lim
206d0 69 74 65 64 20 69 6e 20 73 69 7a 65 20 62 79 20  ited in size by 
206e0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
206f0 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
20700 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
20710 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
20720 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73  s are as follows
20730 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  :.**.** <dl>.** 
20740 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
20750 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
20760 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
20770 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
20780 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
20790 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a  ble row.<dd>.**.
207a0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
207b0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
207c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
207d0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
207e0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
207f0 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
20800 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
20810 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
20820 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
20830 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
20840 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
20850 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
20860 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
20870 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74 68 65   a SELECT or the
20880 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
20890 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
208a0 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
208b0 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
208c0 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
208d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
208e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
208f0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
20900 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
20910 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
20920 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
20930 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  pression.</dd>.*
20940 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
20950 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
20960 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
20970 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
20980 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
20990 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
209a0 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
209b0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
209c0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
209d0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
209e0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
209f0 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
20a00 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
20a10 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
20a20 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
20a30 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
20a40 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
20a50 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
20a60 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
20a70 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
20a80 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
20a90 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
20aa0 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  unction.</dd>.**
20ab0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
20ac0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
20ad0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
20ae0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
20af0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
20b00 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  es.</dd>.**.** <
20b10 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
20b20 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
20b30 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
20b40 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
20b50 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
20b60 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
20b70 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f  e LIKE or.** GLO
20b80 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  B operators.</dd
20b90 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
20ba0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
20bb0 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
20bc0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
20bd0 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61   number of varia
20be0 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73  bles in an SQL s
20bf0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61  tatement that ca
20c00 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f  n.** be bound.</
20c10 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  dd>.** </dl>.*/.
20c20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
20c30 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
20c40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
20c50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20c60 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
20c70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20c80 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
20c90 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
20ca0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20cb0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
20cc0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
20cd0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
20ce0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
20cf0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
20d00 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
20d10 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
20d20 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
20d30 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
20d40 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
20d50 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
20d60 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
20d70 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
20d80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
20d90 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
20da0 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
20db0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
20dc0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
20dd0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
20de0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
20df0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
20e00 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a          9../*.**
20e10 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
20e20 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
20e30 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c  ement {H13010} <
20e40 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10000>.** KEYWO
20e50 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
20e60 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
20e70 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
20e80 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
20e90 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
20ea0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
20eb0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
20ec0 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
20ed0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
20ee0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
20ef0 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
20f00 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
20f10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
20f20 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
20f30 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ior call to [sql
20f40 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
20f50 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20f60 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
20f70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  en16()]..**.** T
20f80 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
20f90 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
20fa0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
20fb0 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
20fc0 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
20fd0 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
20fe0 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
20ff0 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
21000 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21010 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
21020 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
21030 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
21040 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
21050 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
21060 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  * use UTF-16..**
21070 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65  .** If the nByte
21080 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
21090 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
210a0 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
210b0 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
210c0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
210d0 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e  r. If nByte is n
210e0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
210f0 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
21100 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
21110 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
21120 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42  m zSql.  When nB
21130 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
21140 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
21150 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
21160 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
21170 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
21180 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
21190 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68  .** the nByte-th
211a0 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
211b0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66   comes first. If
211c0 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
211d0 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75  s.** that the su
211e0 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
211f0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
21200 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61   then there is a
21210 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72   small.** perfor
21220 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
21230 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20  to be gained by 
21240 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
21250 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
21260 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
21270 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
21280 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
21290 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
212a0 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
212b0 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
212c0 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61  tes..**.** *pzTa
212d0 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
212e0 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
212f0 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65   byte past the e
21300 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  nd of the.** fir
21310 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
21320 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
21330 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63   routines only c
21340 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
21350 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
21360 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
21370 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
21380 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69  ng to what remai
21390 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64  ns.** uncompiled
213a0 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20  ..**.** *ppStmt 
213b0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
213c0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
213d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
213e0 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
213f0 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
21400 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
21410 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  )].  If there is
21420 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
21430 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
21440 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e  NULL.  If the in
21450 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
21460 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
21470 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
21480 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
21490 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
214a0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
214b0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30  o NULL..** {A130
214c0 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  18} The calling 
214d0 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
214e0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
214f0 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
21500 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
21510 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
21520 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
21530 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
21540 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
21550 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
21560 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
21570 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69  eturned, otherwi
21580 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
21590 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
215a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
215b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
215c0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
215d0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
215e0 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
215f0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
21600 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
21610 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
21620 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
21630 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
21640 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
21650 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
21660 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
21670 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22  ..** In the "v2"
21680 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
21690 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
216a0 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
216b0 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
216c0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
216d0 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
216e0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
216f0 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
21700 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
21710 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21720 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
21730 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65  * behave a diffe
21740 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61  rently in two wa
21750 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
21760 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65  * <li>.** If the
21770 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
21780 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
21790 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
217a0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
217b0 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
217c0 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
217d0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
217e0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
217f0 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
21800 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
21810 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
21820 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73  again.  If the s
21830 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65  chema has change
21840 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68  d in.** a way th
21850 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61  at makes the sta
21860 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72  tement no longer
21870 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33   valid, [sqlite3
21880 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74  _step()] will st
21890 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
218a0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20  QLITE_SCHEMA].  
218b0 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c  But unlike the l
218c0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20  egacy behavior, 
218d0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
218e0 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61  is.** now a fata
218f0 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e  l error.  Callin
21900 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
21910 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77  re_v2()] again w
21920 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65  ill not make the
21930 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61  .** error go awa
21940 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73  y.  Note: use [s
21950 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
21960 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78   to find the tex
21970 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73  t.** of the pars
21980 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72  ing error that r
21990 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51  esults in an [SQ
219a0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74  LITE_SCHEMA] ret
219b0 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  urn..** </li>.**
219c0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e  .** <li>.** When
219d0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
219e0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
219f0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
21a00 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
21a10 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
21a20 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
21a30 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
21a40 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
21a50 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
21a60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21a70 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
21a80 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
21a90 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
21aa0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79  lt code.** and y
21ab0 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  ou would have to
21ac0 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
21ad0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
21ae0 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65  reset()] in orde
21af0 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65  r.** to find the
21b00 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
21b10 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
21b20 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
21b30 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
21b40 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
21b50 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
21b60 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
21b70 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
21b80 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ly..** </li>.** 
21b90 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  </ol>.**.** INVA
21ba0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
21bb0 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69  13011} The [sqli
21bc0 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a  te3_prepare(db,z
21bd0 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a  Sql,...)] and.**
21be0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
21bf0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
21c00 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65  ,zSql,...)] inte
21c10 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74  rfaces interpret
21c20 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
21c30 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a   text in their z
21c40 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73  Sql parameter as
21c50 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48   UTF-8..**.** {H
21c60 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  13012} The [sqli
21c70 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 64 62  te3_prepare16(db
21c80 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a  ,zSql,...)] and.
21c90 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
21ca0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
21cb0 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20  2(db,zSql,...)] 
21cc0 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72  interfaces inter
21cd0 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  pret the.**     
21ce0 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65       text in the
21cf0 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65  ir zSql paramete
21d00 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  r as UTF-16 in t
21d10 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
21d20 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  rder..**.** {H13
21d30 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74  013} If the nByt
21d40 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  e argument to [s
21d50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21d60 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  2(db,zSql,nByte,
21d70 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
21d80 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e    and its varian
21d90 74 73 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  ts is less than 
21da0 7a 65 72 6f 2c 20 74 68 65 20 53 51 4c 20 74 65  zero, the SQL te
21db0 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  xt is.**        
21dc0 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c    read from zSql
21dd0 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
21de0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
21df0 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
21e00 7b 48 31 33 30 31 34 7d 20 49 66 20 74 68 65 20  {H13014} If the 
21e10 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74  nByte argument t
21e20 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
21e30 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42  re_v2(db,zSql,nB
21e40 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  yte,...)].**    
21e50 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61        and its va
21e60 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65  riants is non-ne
21e70 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20  gative, then at 
21e80 6d 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74 65  most nBytes byte
21e90 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s of.**         
21ea0 20 53 51 4c 20 74 65 78 74 20 69 73 20 72 65 61   SQL text is rea
21eb0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a  d from zSql..**.
21ec0 2a 2a 20 7b 48 31 33 30 31 35 7d 20 49 6e 20 5b  ** {H13015} In [
21ed0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21ee0 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70  v2(db,zSql,N,P,p
21ef0 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69 74 73 20  zTail)] and its 
21f00 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20  variants.**     
21f10 20 20 20 20 20 69 66 20 74 68 65 20 7a 53 71 6c       if the zSql
21f20 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
21f30 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  ains more than o
21f40 6e 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ne SQL statement
21f50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
21f60 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
21f70 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69  ULL, then *pzTai
21f80 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
21f90 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  nt to the.**    
21fa0 20 20 20 20 20 20 66 69 72 73 74 20 62 79 74 65        first byte
21fb0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
21fc0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
21fd0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
21fe0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74  ..**          <t
21ff0 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73 20 2a 70  odo>What does *p
22000 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69  zTail point to i
22010 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65 20 73  f there is one s
22020 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e  tatement?</todo>
22030 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 36 7d 20  .**.** {H13016} 
22040 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
22050 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  l to [sqlite3_pr
22060 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
22070 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a  ,N,ppStmt,...)].
22080 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 6f  **          or o
22090 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
220a0 74 73 20 77 72 69 74 65 73 20 69 6e 74 6f 20 2a  ts writes into *
220b0 70 70 53 74 6d 74 20 61 20 70 6f 69 6e 74 65 72  ppStmt a pointer
220c0 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20   to a new.**    
220d0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
220e0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20  statement] or a 
220f0 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20  pointer to NULL 
22100 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73  if zSql contains
22110 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74  .**          not
22120 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
22130 77 68 69 74 65 73 70 61 63 65 20 6f 72 20 63 6f  whitespace or co
22140 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  mments..**.** {H
22150 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71 6c 69  13019} The [sqli
22160 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
22170 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20  ] interface and 
22180 69 74 73 20 76 61 72 69 61 6e 74 73 20 72 65 74  its variants ret
22190 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
221a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61  [SQLITE_OK] or a
221b0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
221c0 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20  rror code] upon 
221d0 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b  failure..**.** {
221e0 48 31 33 30 32 31 7d 20 42 65 66 6f 72 65 20 5b  H13021} Before [
221f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
22200 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70  db,zSql,nByte,pp
22210 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72  Stmt,pzTail)] or
22220 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20   its.**         
22230 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e   variants return
22240 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e 79 20  s an error (any 
22250 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
22260 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a   [SQLITE_OK]),.*
22270 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 79 20  *          they 
22280 66 69 72 73 74 20 73 65 74 20 2a 70 70 53 74 6d  first set *ppStm
22290 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  t to NULL..*/.in
222a0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
222b0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
222c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
222d0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
222e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
222f0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
22300 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
22310 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
22320 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
22330 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
22340 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
22350 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
22360 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
22370 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
22380 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
22390 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
223a0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
223b0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
223c0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
223d0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
223e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
223f0 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
22400 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
22410 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
22420 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
22430 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
22440 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
22450 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
22460 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
22470 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
22480 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
22490 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
224a0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
224b0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
224c0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
224d0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
224e0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
224f0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
22500 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
22510 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
22520 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
22530 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
22540 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
22550 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
22560 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
22570 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
22580 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
22590 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
225a0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
225b0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
225c0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
225d0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
225e0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
225f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
22600 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
22610 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
22620 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
22630 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
22640 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
22650 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
22660 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
22670 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
22680 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
22690 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
226a0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
226b0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
226c0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
226d0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
226e0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
226f0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
22700 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
22710 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
22720 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
22730 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
22740 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
22750 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
22760 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
22770 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
22780 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
22790 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
227a0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
227b0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
227c0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
227d0 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20  g Statement SQL 
227e0 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30  {H13100} <H13000
227f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  >.**.** This int
22800 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
22810 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
22820 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
22830 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
22840 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
22850 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
22860 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
22870 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
22880 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
22890 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
228a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
228b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
228c0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
228d0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
228e0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 31  S:.**.** {H13101
228f0 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72  } If the [prepar
22900 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61  ed statement] pa
22910 73 73 65 64 20 61 73 20 74 68 65 20 61 72 67 75  ssed as the argu
22920 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20  ment to.**      
22930 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c      [sqlite3_sql
22940 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ()] was compiled
22950 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
22960 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22970 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  2()] or.**      
22980 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
22990 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 74 68  pare16_v2()], th
229a0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28  en [sqlite3_sql(
229b0 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  )] returns.**   
229c0 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72         a pointer
229d0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
229e0 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e  nated string con
229f0 74 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20  taining a UTF-8 
22a00 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20  rendering.**    
22a10 20 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69        of the ori
22a20 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d  ginal SQL statem
22a30 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31  ent..**.** {H131
22a40 30 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70  02} If the [prep
22a50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22a60 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72  passed as the ar
22a70 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20  gument to.**    
22a80 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
22a90 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c  ql()] was compil
22aa0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
22ab0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22ac0 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
22ad0 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
22ae0 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 5b  are16()], then [
22af0 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72  sqlite3_sql()] r
22b00 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
22b10 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  inter..**.** {H1
22b20 33 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e 67  3103} The string
22b30 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
22b40 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69 73  lite3_sql(S)] is
22b50 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
22b60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
22b70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22b80 5d 20 53 20 69 73 20 64 65 6c 65 74 65 64 20 75  ] S is deleted u
22b90 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
22ba0 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63  nalize(S)]..*/.c
22bb0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
22bc0 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
22bd0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
22be0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
22bf0 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
22c00 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48 31  Value Object {H1
22c10 35 30 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  5000} <S20200>.*
22c20 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
22c30 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
22c40 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
22c50 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
22c60 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
22c70 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
22c80 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
22c90 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
22ca0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
22cb0 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
22cc0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
22cd0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
22ce0 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
22cf0 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
22d00 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 20 73  stores. Values s
22d10 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
22d20 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
22d30 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
22d40 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
22d50 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
22d60 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
22d70 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
22d80 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
22d90 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
22da0 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
22db0 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
22dc0 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
22dd0 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
22de0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
22df0 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
22e00 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
22e10 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
22e20 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
22e30 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
22e40 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
22e50 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
22e60 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
22e70 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
22e80 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
22e90 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
22ea0 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
22eb0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
22ec0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
22ed0 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
22ee0 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
22ef0 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
22f00 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
22f10 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20  tex is held.  A 
22f20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
22f30 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
22f40 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
22f50 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
22f60 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
22f70 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
22f80 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
22f90 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
22fa0 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
22fb0 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
22fc0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
22fd0 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
22fe0 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
22ff0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
23000 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
23010 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
23020 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
23030 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
23040 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
23050 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
23060 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
23070 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
23080 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
23090 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
230a0 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
230b0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
230c0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
230d0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
230e0 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
230f0 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
23100 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
23110 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
23120 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
23130 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
23140 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
23150 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
23160 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
23170 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
23180 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  en between prote
23190 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
231a0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
231b0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
231c0 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
231d0 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
231e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
231f0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
23200 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
23210 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
23220 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
23230 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
23240 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
23250 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
23260 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
23270 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
23280 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
23290 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
232a0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
232b0 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
232c0 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
232d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
232e0 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
232f0 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
23300 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
23310 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
23320 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
23330 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
23340 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
23350 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
23360 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
23370 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
23380 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
23390 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
233a0 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
233b0 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
233c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
233d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
233e0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
233f0 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 36 30  ext Object {H160
23400 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  01} <S20200>.**.
23410 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
23420 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
23430 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
23440 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
23450 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
23460 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70  ext object.  A p
23470 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
23480 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
23490 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
234a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
234b0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
234c0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
234d0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
234e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
234f0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
23500 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
23510 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
23520 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
23530 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
23540 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
23550 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
23560 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
23570 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
23580 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
23590 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
235a0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
235b0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
235c0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
235d0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
235e0 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
235f0 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
23600 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
23610 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
23620 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
23630 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
23640 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
23650 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
23660 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 35 30  tatements {H1350
23670 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b  0} <S70300>.** K
23680 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
23690 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
236a0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
236b0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
236c0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
236d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
236e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
236f0 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
23700 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ng}.**.** In the
23710 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70   SQL strings inp
23720 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
23730 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
23740 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
23750 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
23760 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
23770 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65  parameter in one
23780 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a   of these forms:
23790 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
237a0 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
237b0 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
237c0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
237d0 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
237e0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
237f0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66   the parameter f
23800 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  orms shown above
23810 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67   NNN is an integ
23820 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
23830 6e 64 20 56 56 56 20 69 73 20 61 6e 20 61 6c 70  nd VVV is an alp
23840 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d  ha-numeric param
23850 65 74 65 72 20 6e 61 6d 65 2e 20 54 68 65 20 76  eter name. The v
23860 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
23870 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
23880 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
23890 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
238a0 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
238b0 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
238c0 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
238d0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
238e0 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
238f0 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  here..**.** The 
23900 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
23910 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
23920 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
23930 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
23940 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
23950 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
23960 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
23970 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
23980 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
23990 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
239a0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
239b0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
239c0 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
239d0 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
239e0 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d  et..** The leftm
239f0 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
23a00 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
23a10 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73  f 1.  When the s
23a20 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
23a30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
23a40 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
23a50 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
23a60 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
23a70 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
23a80 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
23a90 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
23aa0 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65  nce..** The inde
23ab0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
23ac0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
23ad0 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
23ae0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
23af0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
23b00 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
23b10 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78  ired.  The index
23b20 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
23b30 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
23b40 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
23b50 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20  * The NNN value 
23b60 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
23b70 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
23b80 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
23b90 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
23ba0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
23bb0 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
23bc0 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
23bd0 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72  .** The third ar
23be0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
23bf0 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
23c00 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
23c10 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f 75  .** In those rou
23c20 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
23c30 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
23c40 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
23c50 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
23c60 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
23c70 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
23c80 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
23c90 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
23ca0 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
23cb0 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
23cc0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
23cd0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
23ce0 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
23cf0 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
23d00 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68  tive, the length
23d10 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
23d20 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
23d30 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
23d40 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
23d50 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
23d60 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
23d70 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
23d80 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
23d90 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
23da0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  and.** sqlite3_b
23db0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20  ind_text16() is 
23dc0 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
23dd0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
23de0 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
23df0 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
23e00 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
23e10 77 69 74 68 20 69 74 2e 20 49 66 20 74 68 65 20  with it. If the 
23e20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
23e30 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
23e40 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
23e50 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
23e60 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
23e70 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
23e80 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
23e90 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
23ea0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
23eb0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
23ec0 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74 68  .** If the fifth
23ed0 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
23ee0 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
23ef0 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
23f00 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
23f10 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
23f20 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
23f30 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
23f40 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
23f50 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
23f60 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
23f70 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23f80 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
23f90 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
23fa0 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
23fb0 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
23fc0 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
23fd0 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65    A zeroblob use
23fe0 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
23ff0 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
24000 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
24010 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
24020 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
24030 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
24040 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
24050 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
24060 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
24070 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
24080 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
24090 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
240a0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
240b0 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
240c0 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
240d0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20   routines..** A 
240e0 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
240f0 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
24100 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
24110 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
24120 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
24130 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
24140 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
24150 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69  d after.** [sqli
24160 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
24170 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69 61  ] (and its varia
24180 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33  nts) or [sqlite3
24190 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a  _reset()] and.**
241a0 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   before [sqlite3
241b0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e  _step()]..** Bin
241c0 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
241d0 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
241e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
241f0 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75  outine..** Unbou
24200 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
24210 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
24220 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
24230 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
24240 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
24250 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20  n success or an 
24260 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a  error code if.**
24270 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
24280 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52  rong.  [SQLITE_R
24290 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
242a0 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
242b0 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
242c0 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53  ut of range.  [S
242d0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
242e0 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
242f0 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b  oc() fails..** [
24300 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
24310 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
24320 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   if these routin
24330 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e  es are called on
24340 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61   a.** virtual ma
24350 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74 68  chine that is th
24360 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72  e wrong state or
24370 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65 61   which has alrea
24380 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  dy been finalize
24390 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20  d..** Detection 
243a0 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75 6e 72  of misuse is unr
243b0 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c 69 63  eliable.  Applic
243c0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
243d0 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53  t depend.** on S
243e0 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 65 74  QLITE_MISUSE ret
243f0 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49  urns.  SQLITE_MI
24400 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64 65 64  SUSE is intended
24410 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61 0a 2a   to indicate a.*
24420 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f 72 20  * a logic error 
24430 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  in the applicati
24440 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  on.  Future vers
24450 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
24460 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61  ight.** panic ra
24470 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e  ther than return
24480 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
24490 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
244a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
244b0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
244c0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
244d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
244e0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
244f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
24500 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
24510 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
24520 0a 2a 2a 20 7b 48 31 33 35 30 36 7d 20 54 68 65  .** {H13506} The
24530 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   [SQL statement 
24540 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e  compiler] recogn
24550 69 7a 65 73 20 74 6f 6b 65 6e 73 20 6f 66 20 74  izes tokens of t
24560 68 65 20 66 6f 72 6d 73 0a 2a 2a 20 20 20 20 20  he forms.**     
24570 20 20 20 20 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22       "?", "?NNN"
24580 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22  , "$VVV", ":VVV"
24590 2c 20 61 6e 64 20 22 40 56 56 56 22 20 61 73 20  , and "@VVV" as 
245a0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2c 0a  SQL parameters,.
245b0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72  **          wher
245c0 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65 71  e NNN is any seq
245d0 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20  uence of one or 
245e0 6d 6f 72 65 20 64 69 67 69 74 73 0a 2a 2a 20 20  more digits.**  
245f0 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65 72          and wher
24600 65 20 56 56 56 20 69 73 20 61 6e 79 20 73 65 71  e VVV is any seq
24610 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20  uence of one or 
24620 6d 6f 72 65 20 61 6c 70 68 61 6e 75 6d 65 72 69  more alphanumeri
24630 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68  c.**          ch
24640 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a 22  aracters or "::"
24650 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c   optionally foll
24660 6f 77 65 64 20 62 79 20 61 20 73 74 72 69 6e 67  owed by a string
24670 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20   containing.**  
24680 20 20 20 20 20 20 20 20 6e 6f 20 73 70 61 63 65          no space
24690 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20  s and contained 
246a0 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73  within parenthes
246b0 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30  es..**.** {H1350
246c0 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20 76  9} The initial v
246d0 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 70  alue of an SQL p
246e0 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
246f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 32 7d  ..**.** {H13512}
24700 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   The index of an
24710 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65 74   "?" SQL paramet
24720 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65 72  er is one larger
24730 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20   than the.**    
24740 20 20 20 20 20 20 6c 61 72 67 65 73 74 20 69 6e        largest in
24750 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d  dex of SQL param
24760 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66 74  eter to the left
24770 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20 20  , or 1 if.**    
24780 20 20 20 20 20 20 74 68 65 20 22 3f 22 20 69 73        the "?" is
24790 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51   the leftmost SQ
247a0 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  L parameter..**.
247b0 2a 2a 20 7b 48 31 33 35 31 35 7d 20 54 68 65 20  ** {H13515} The 
247c0 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e  index of an "?NN
247d0 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  N" SQL parameter
247e0 20 69 73 20 74 68 65 20 69 6e 74 65 67 65 72 20   is the integer 
247f0 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  NNN..**.** {H135
24800 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  18} The index of
24810 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56 56   an ":VVV", "$VV
24820 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53 51  V", or "@VVV" SQ
24830 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  L parameter is.*
24840 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
24850 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65 78  ame as the index
24860 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63   of leftmost occ
24870 75 72 72 65 6e 63 65 73 20 6f 66 20 74 68 65 20  urrences of the 
24880 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
24890 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f   parameter, or o
248a0 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65  ne more than the
248b0 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f   largest index o
248c0 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ver all.**      
248d0 20 20 20 20 70 61 72 61 6d 65 74 65 72 73 20 74      parameters t
248e0 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20 74 68  o the left if th
248f0 69 73 20 69 73 20 74 68 65 20 66 69 72 73 74 20  is is the first 
24900 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20 20 20  occurrence.**   
24910 20 20 20 20 20 20 20 6f 66 20 74 68 69 73 20 70         of this p
24920 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69  arameter, or 1 i
24930 66 20 74 68 69 73 20 69 73 20 74 68 65 20 6c 65  f this is the le
24940 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72  ftmost parameter
24950 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 31 7d  ..**.** {H13521}
24960 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d   The [SQL statem
24970 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61  ent compiler] fa
24980 69 6c 73 20 77 69 74 68 20 61 6e 20 5b 53 51 4c  ils with an [SQL
24990 49 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20 20 20  ITE_RANGE].**   
249a0 20 20 20 20 20 20 20 65 72 72 6f 72 20 69 66 20         error if 
249b0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
249c0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
249d0 20 6c 65 73 73 20 74 68 61 6e 20 31 0a 2a 2a 20   less than 1.** 
249e0 20 20 20 20 20 20 20 20 20 6f 72 20 67 72 65 61           or grea
249f0 74 65 72 20 74 68 61 6e 20 74 68 65 20 63 6f 6d  ter than the com
24a00 70 69 6c 65 2d 74 69 6d 65 20 53 51 4c 49 54 45  pile-time SQLITE
24a10 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55  _MAX_VARIABLE_NU
24a20 4d 42 45 52 0a 2a 2a 20 20 20 20 20 20 20 20 20  MBER.**         
24a30 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
24a40 2a 20 7b 48 31 33 35 32 34 7d 20 43 61 6c 6c 73  * {H13524} Calls
24a50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
24a60 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33  d_text | sqlite3
24a70 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29  _bind(S,N,V,...)
24a80 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  ].**          as
24a90 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c 75  sociate the valu
24aa0 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51 4c  e V with all SQL
24ab0 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 76 69   parameters havi
24ac0 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ng an.**        
24ad0 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e 20    index of N in 
24ae0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24af0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
24b00 2a 20 7b 48 31 33 35 32 37 7d 20 43 61 6c 6c 73  * {H13527} Calls
24b10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
24b20 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33  d_text | sqlite3
24b30 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a  _bind(S,N,...)].
24b40 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72  **          over
24b50 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c 73  ride prior calls
24b60 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76   with the same v
24b70 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20 4e  alues of S and N
24b80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 30 7d  ..**.** {H13530}
24b90 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62 6c   Bindings establ
24ba0 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74 65  ished by [sqlite
24bb0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71  3_bind_text | sq
24bc0 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e  lite3_bind(S,...
24bd0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  )].**          p
24be0 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 63 61  ersist across ca
24bf0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
24c00 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a  reset(S)]..**.**
24c10 20 7b 48 31 33 35 33 33 7d 20 49 6e 20 63 61 6c   {H13533} In cal
24c20 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
24c30 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
24c40 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
24c50 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
24c60 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
24c70 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
24c80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
24c90 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
24ca0 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 74  ] SQLite binds t
24cb0 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20 20  he first L.**   
24cc0 20 20 20 20 20 20 20 62 79 74 65 73 20 6f 66 20         bytes of 
24cd0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
24ce0 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
24cf0 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20 20   V, when L.**   
24d00 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e 65         is non-ne
24d10 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  gative..**.** {H
24d20 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73 20  13536} In calls 
24d30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
24d40 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
24d50 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
24d60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
24d70 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
24d80 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 63  ] SQLite binds c
24d90 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20 20  haracters.**    
24da0 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68 72        from V thr
24db0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
24dc0 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 77 68  ero character wh
24dd0 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65  en L is negative
24de0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 39 7d  ..**.** {H13539}
24df0 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
24e00 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
24e10 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
24e20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
24e30 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
24e40 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
24e50 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
24e60 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
24e70 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
24e80 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a  is the special.*
24e90 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  *          const
24ea0 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  ant [SQLITE_STAT
24eb0 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73 75  IC], SQLite assu
24ec0 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 61 6c  mes that the val
24ed0 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20 20  ue V.**         
24ee0 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61 74   is held in stat
24ef0 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  ic unmanaged spa
24f00 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f 74  ce that will not
24f10 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20   change.**      
24f20 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20 6c      during the l
24f30 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 62  ifetime of the b
24f40 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  inding..**.** {H
24f50 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73 20  13542} In calls 
24f60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
24f70 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _blob(S,N,V,L,D)
24f80 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
24f90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
24fa0 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f  t(S,N,V,L,D)], o
24fb0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
24fc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24fd0 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77  16(S,N,V,L,D)] w
24fe0 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65  hen D is the spe
24ff0 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  cial.**         
25000 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54   constant [SQLIT
25010 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
25020 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20  e routine makes 
25030 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  a.**          pr
25040 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
25050 65 20 76 61 6c 75 65 20 56 20 62 65 66 6f 72 65  e value V before
25060 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
25070 2a 2a 20 7b 48 31 33 35 34 35 7d 20 49 6e 20 63  ** {H13545} In c
25080 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
25090 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56  _bind_blob(S,N,V
250a0 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,L,D)],.**      
250b0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
250c0 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
250d0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
250e0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
250f0 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c  _text16(S,N,V,L,
25100 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20  D)] when D is a 
25110 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20  pointer to.**   
25120 20 20 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f         a functio
25130 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  n, SQLite invoke
25140 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  s that function 
25150 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a  to destroy the.*
25160 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
25170 20 56 20 61 66 74 65 72 20 69 74 20 68 61 73 20   V after it has 
25180 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
25190 68 65 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a  he value V..**.*
251a0 2a 20 7b 48 31 33 35 34 38 7d 20 49 6e 20 63 61  * {H13548} In ca
251b0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
251c0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c  bind_zeroblob(S,
251d0 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75  N,V,L)] the valu
251e0 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20  e bound.**      
251f0 20 20 20 20 69 73 20 61 20 42 4c 4f 42 20 6f 66      is a BLOB of
25200 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a   L bytes, or a z
25210 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
25220 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65  if L is negative
25230 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 35 31 7d  ..**.** {H13551}
25240 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
25250 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
25260 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20 61  (S,N,V)] the V a
25270 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20  rgument may.**  
25280 20 20 20 20 20 20 20 20 62 65 20 65 69 74 68 65          be eithe
25290 72 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73  r a [protected s
252a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
252b0 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20  ject or an.**   
252c0 20 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 65 63         [unprotec
252d0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
252e0 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e  e] object..*/.in
252f0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
25300 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
25310 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
25320 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
25330 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
25340 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
25350 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
25360 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
25370 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
25380 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
25390 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
253a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
253b0 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
253c0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
253d0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
253e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
253f0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
25400 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
25410 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
25420 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
25430 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
25440 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
25450 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
25460 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
25470 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25480 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
25490 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
254a0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
254b0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
254c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
254d0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
254e0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
254f0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
25500 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25510 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
25520 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
25530 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
25540 6d 65 74 65 72 73 20 7b 48 31 33 36 30 30 7d 20  meters {H13600} 
25550 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70300>.**.** T
25560 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
25570 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
25580 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
25590 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
255a0 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
255b0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
255c0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
255d0 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
255e0 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
255f0 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
25600 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
25610 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
25620 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
25630 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
25640 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
25650 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
25660 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
25670 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
25680 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
25690 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
256a0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
256b0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
256c0 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
256d0 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
256e0 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
256f0 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
25700 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
25710 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
25720 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
25730 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
25740 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75  f the ?NNN are u
25750 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
25760 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
25770 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   list..**.** See
25780 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
25790 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
257a0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
257b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
257c0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
257d0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
257e0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
257f0 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
25800 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
25810 7b 48 31 33 36 30 31 7d 20 54 68 65 20 5b 73 71  {H13601} The [sq
25820 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
25830 65 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69  eter_count(S)] i
25840 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
25860 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f   largest index o
25870 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65  f all SQL parame
25880 74 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ters in the.**  
25890 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
258a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20  d statement] S, 
258b0 6f 72 20 30 20 69 66 20 53 20 63 6f 6e 74 61 69  or 0 if S contai
258c0 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65  ns no SQL parame
258d0 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ters..*/.int sql
258e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
258f0 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
25900 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
25910 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
25920 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
25930 74 65 72 20 7b 48 31 33 36 32 30 7d 20 3c 53 37  ter {H13620} <S7
25940 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0300>.**.** This
25950 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
25960 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
25970 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d  e name of the n-
25980 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d  th.** [SQL param
25990 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 72 65 70  eter] in a [prep
259a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
259b0 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
259c0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
259d0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
259e0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
259f0 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
25a00 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
25a10 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
25a20 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
25a30 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
25a40 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
25a50 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
25a60 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
25a70 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
25a80 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
25a90 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
25aa0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61  he name..** Para
25ab0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
25ac0 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
25ad0 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
25ae0 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
25af0 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73 6f 20  ** and are also 
25b00 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
25b10 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
25b20 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ters"..**.** The
25b30 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
25b40 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
25b50 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
25b60 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c  **.** If the val
25b70 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue n is out of r
25b80 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e  ange or if the n
25b90 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
25ba0 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
25bb0 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
25bc0 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e  ned.  The return
25bd0 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
25be0 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
25bf0 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
25c00 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
25c10 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
25c20 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
25c30 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
25c40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25c50 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
25c60 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
25c70 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
25c80 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
25c90 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
25ca0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
25cb0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25cc0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
25cd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
25ce0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
25cf0 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
25d00 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
25d10 31 33 36 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  13621} The [sqli
25d20 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25d30 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  er_name(S,N)] in
25d40 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
25d50 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 55 54  **          a UT
25d60 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
25d70 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
25d80 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
25d90 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
25da0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
25db0 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e 67 20  ement] S having 
25dc0 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20  index N, or.**  
25dd0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 66 20          NULL if 
25de0 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51 4c 20  there is no SQL 
25df0 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69  parameter with i
25e00 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74 68 65  ndex N or if the
25e10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
25e20 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65  ameter with inde
25e30 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79 6d  x N is an anonym
25e40 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20 22 3f  ous parameter "?
25e50 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  "..*/.const char
25e60 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
25e70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
25e80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25e90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25ea0 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
25eb0 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
25ec0 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36  Given Name {H136
25ed0 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  40} <S70300>.**.
25ee0 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e  ** Return the in
25ef0 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
25f00 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
25f10 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20  s name.  The.** 
25f20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
25f30 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
25f40 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
25f50 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
25f60 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
25f70 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
25f80 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65  3_bind()].  A ze
25f90 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
25fa0 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
25fb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
25fc0 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65  und.  The parame
25fd0 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
25fe0 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
25ff0 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
26000 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
26010 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
26020 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
26030 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
26040 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
26050 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
26060 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
26070 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
26080 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
26090 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
260a0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
260b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
260c0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
260d0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
260e0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
260f0 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3641} The [sqlit
26100 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
26110 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e  r_index(S,N)] in
26120 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
26130 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
26140 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72  index of SQL par
26150 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 5b 70  ameter in the [p
26160 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26170 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  t].**          S
26180 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74 63   whose name matc
26190 68 65 73 20 74 68 65 20 55 54 46 2d 38 20 73 74  hes the UTF-8 st
261a0 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66 20  ring N, or 0 if 
261b0 74 68 65 72 65 20 69 73 0a 2a 2a 20 20 20 20 20  there is.**     
261c0 20 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a       no match..*
261d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
261e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
261f0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
26200 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
26210 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
26220 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
26230 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
26240 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
26250 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30 33  t {H13660} <S703
26260 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61  00>.**.** Contra
26270 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
26280 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
26290 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
262a0 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
262b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
262c0 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
262d0 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
262e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
262f0 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69  * Use this routi
26300 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
26310 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
26320 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49  to NULL..**.** I
26330 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
26340 20 7b 48 31 33 36 36 31 7d 20 54 68 65 20 5b 73   {H13661} The [s
26350 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
26360 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66  dings(S)] interf
26370 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c 20 53  ace resets all S
26380 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  QL.**          p
26390 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
263a0 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  s in the [prepar
263b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
263c0 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  back to NULL..*/
263d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
263e0 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
263f0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
26400 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
26410 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
26420 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
26430 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30 30 3e  H13710} <S10700>
26440 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
26450 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
26460 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
26470 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
26480 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
26490 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54  ed statement]. T
264a0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
264b0 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
264c0 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
264d0 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
264e0 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
264f0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
26500 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
26510 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
26520 2a 2a 20 7b 48 31 33 37 31 31 7d 20 54 68 65 20  ** {H13711} The 
26530 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26540 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66  count(S)] interf
26550 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
26560 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20  number of.**    
26570 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69 6e        columns in
26580 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
26590 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 68 65  generated by the
265a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
265b0 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20  ment] S,.**     
265c0 20 20 20 20 20 6f 72 20 30 20 69 66 20 53 20 64       or 0 if S d
265d0 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74 65  oes not generate
265e0 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a   a result set..*
265f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
26600 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
26610 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
26620 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26630 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
26640 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
26650 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30 30 3e  H13720} <S10700>
26660 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
26670 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
26680 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
26690 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
266a0 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
266b0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
266c0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
266d0 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  nt.  The sqlite3
266e0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
266f0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
26700 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
26710 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
26720 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
26730 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
26740 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
26750 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
26760 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
26770 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
26780 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72  string.  The fir
26790 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
267a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
267b0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
267c0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
267d0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
267e0 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  nt. The second p
267f0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
26800 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
26810 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  .  The leftmost 
26820 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
26830 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65   0..**.** The re
26840 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
26850 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
26860 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
26870 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26880 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
26890 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
268a0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
268b0 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
268c0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
268d0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
268e0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
268f0 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
26900 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
26910 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  *.** If sqlite3_
26920 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
26930 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
26940 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
26950 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
26960 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
26970 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
26980 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
26990 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
269a0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
269b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ned..**.** The n
269c0 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
269d0 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
269e0 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
269f0 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
26a00 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
26a10 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
26a20 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
26a30 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
26a40 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
26a50 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
26a60 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
26a70 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
26a80 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
26a90 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
26aa0 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   next..**.** INV
26ab0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
26ac0 48 31 33 37 32 31 7d 20 41 20 73 75 63 63 65 73  H13721} A succes
26ad0 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
26ae0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
26af0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29  column_name(S,N)
26b00 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
26b10 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
26b20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
26b30 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72  Nth column (wher
26b40 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  e 0 is.**       
26b50 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20     the leftmost 
26b60 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20  column) for the 
26b70 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
26b80 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
26b90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26ba0 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74  t] S as a zero-t
26bb0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
26bc0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
26bd0 31 33 37 32 33 7d 20 41 20 73 75 63 63 65 73 73  13723} A success
26be0 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
26bf0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
26c00 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e  olumn_name16(S,N
26c10 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
26c20 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
26c30 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
26c40 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65   Nth column (whe
26c50 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20  re 0 is.**      
26c60 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74      the leftmost
26c70 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65   column) for the
26c80 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
26c90 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
26ca0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26cb0 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d  nt] S as a zero-
26cc0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31  terminated UTF-1
26cd0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  6 string.**     
26ce0 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69       in the nati
26cf0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
26d00 2a 0a 2a 2a 20 7b 48 31 33 37 32 34 7d 20 54 68  *.** {H13724} Th
26d10 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
26d20 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73  n_name()] and [s
26d30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
26d40 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20  me16()].**      
26d50 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72      interfaces r
26d60 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  eturn a NULL poi
26d70 6e 74 65 72 20 69 66 20 74 68 65 79 20 61 72 65  nter if they are
26d80 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20   unable to.**   
26d90 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20         allocate 
26da0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
26db0 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74 75  heir normal retu
26dc0 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a  rn strings..**.*
26dd0 2a 20 7b 48 31 33 37 32 35 7d 20 49 66 20 74 68  * {H13725} If th
26de0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
26df0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26e00 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a  _name(S,N)] or.*
26e10 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
26e20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
26e30 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f  6(S,N)] is out o
26e40 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68  f range, then th
26e50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
26e60 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
26e70 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
26e80 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 36 7d 20 54  **.** {H13726} T
26e90 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
26ea0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
26eb0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29  column_name(S,N)
26ec0 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
26ed0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
26ee0 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61  n_name16(S,N)] a
26ef0 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  re valid until t
26f00 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20  he next.**      
26f10 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74 68      call to eith
26f20 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  er routine with 
26f30 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20 4e  the same S and N
26f40 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20   parameters.**  
26f50 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c          or until
26f60 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
26f70 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64  ze(S)] is called
26f80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 37 7d  ..**.** {H13727}
26f90 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20 63   When a result c
26fa0 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45  olumn of a [SELE
26fb0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  CT] statement co
26fc0 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20  ntains.**       
26fd0 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2c     an AS clause,
26fe0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 61   the name of tha
26ff0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
27000 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20  identifier.**   
27010 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 72 69         to the ri
27020 67 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b 65  ght of the AS ke
27030 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  yword..*/.const 
27040 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
27050 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
27060 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
27070 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
27080 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
27090 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
270a0 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
270b0 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
270c0 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
270d0 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33  uery Result {H13
270e0 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  740} <S10700>.**
270f0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
27100 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
27110 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
27120 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77  what column of w
27130 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20  hat.** table in 
27140 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61  which database a
27150 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b 53 45   result of a [SE
27160 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
27170 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54  comes from..** T
27180 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
27190 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
271a0 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
271b0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
271c0 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
271d0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
271e0 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65  .  The _database
271f0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
27200 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
27210 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
27220 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
27230 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
27240 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
27250 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
27260 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
27270 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72  n name..** The r
27280 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
27290 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
272a0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
272b0 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
272c0 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
272d0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
272e0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
272f0 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
27300 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
27310 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
27320 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
27330 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72  *.** The names r
27340 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
27350 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
27360 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
27370 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
27380 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
27390 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
273a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
273b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73   following calls
273c0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
273d0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54  statement]..** T
273e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
273f0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
27400 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
27410 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
27420 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
27430 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
27440 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
27450 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
27460 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63  .** If the Nth c
27470 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
27480 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
27490 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
274a0 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
274b0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
274c0 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
274d0 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
274e0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
274f0 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f   NULL.  These ro
27500 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
27510 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
27520 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
27530 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
27540 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  urs.  Otherwise,
27550 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
27560 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
27570 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
27580 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c  table.** and col
27590 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
275a0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
275b0 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
275c0 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61  .**.** As with a
275d0 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
275e0 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74  APIs, those post
275f0 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20  fixed with "16" 
27600 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
27610 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
27620 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  , the other func
27630 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
27640 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  -8. {END}.**.** 
27650 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
27660 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
27670 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
27680 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
27690 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
276a0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
276b0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
276c0 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
276d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37  ned..**.** {A137
276e0 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  51}.** If two or
276f0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
27700 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
27710 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
27720 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
27730 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
27740 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
27750 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
27760 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
27770 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
27780 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  fined..**.** INV
27790 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
277a0 48 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71 6c  H13741} The [sql
277b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
277c0 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  base_name(S,N)] 
277d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
277e0 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
277f0 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a       the UTF-8 z
27800 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
27810 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
27820 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ase from which t
27830 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
27840 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
27850 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
27860 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
27870 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20  s extracted,.** 
27880 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
27890 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
278a0 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
278b0 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
278c0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
278d0 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
278e0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
278f0 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
27900 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 7d 20 54 68  *.** {H13742} Th
27910 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
27920 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
27930 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
27940 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
27950 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
27960 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
27970 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74  yte order zero-t
27980 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
27990 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
279a0 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
279b0 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65  which the Nth re
279c0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
279d0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
279e0 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20  tement] S is.** 
279f0 20 20 20 20 20 20 20 20 20 65 78 74 72 61 63 74           extract
27a00 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
27a10 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
27a20 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
27a30 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
27a40 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
27a50 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
27a60 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
27a70 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
27a80 7b 48 31 33 37 34 33 7d 20 54 68 65 20 5b 73 71  {H13743} The [sq
27a90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
27aa0 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  le_name(S,N)] in
27ab0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27ac0 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
27ad0 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72     the UTF-8 zer
27ae0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
27af0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66  e of the table f
27b00 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a  rom which the.**
27b10 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
27b20 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
27b30 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
27b40 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74  tement] S is ext
27b50 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20  racted,.**      
27b60 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74      or NULL if t
27b70 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
27b80 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
27b90 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
27ba0 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
27bb0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
27bc0 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
27bd0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
27be0 7b 48 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71  {H13744} The [sq
27bf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
27c00 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  le_name16(S,N)] 
27c10 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27c20 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
27c30 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20       the UTF-16 
27c40 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
27c50 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  r zero-terminate
27c60 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
27c70 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ble.**          
27c80 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e  from which the N
27c90 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
27ca0 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
27cb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
27cc0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
27cd0 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
27ce0 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
27cf0 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
27d00 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
27d10 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
27d20 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
27d30 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
27d40 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
27d50 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 7d 20 54 68  *.** {H13745} Th
27d60 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
27d70 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53 2c  n_origin_name(S,
27d80 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
27d90 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
27da0 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
27db0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
27dc0 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
27dd0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d  able column from
27de0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20   which the.**   
27df0 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c         Nth resul
27e00 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
27e10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27e20 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63  ent] S is extrac
27e30 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ted,.**         
27e40 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
27e50 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
27e60 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70  is a general exp
27e70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  ression.**      
27e80 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65      or if unable
27e90 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
27ea0 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65  ory to store the
27eb0 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   name..**.** {H1
27ec0 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  3746} The [sqlit
27ed0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
27ee0 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e  _name16(S,N)] in
27ef0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27f00 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
27f10 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61     the UTF-16 na
27f20 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
27f30 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
27f40 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
27f50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
27f60 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20  lumn from which 
27f70 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
27f80 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
27f90 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
27fa0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
27fb0 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72  is extracted, or
27fc0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
27fd0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20   column.**      
27fe0 20 20 20 20 6f 66 20 53 20 69 73 20 61 20 67 65      of S is a ge
27ff0 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
28000 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
28010 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
28020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
28030 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
28040 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 38 7d 20 54  **.** {H13748} T
28050 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  he return values
28060 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20   from.**        
28070 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
28080 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
28090 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
280a0 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
280b0 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61            are va
280c0 6c 69 64 20 66 6f 72 20 74 68 65 20 6c 69 66 65  lid for the life
280d0 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65  time of the [pre
280e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
280f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
28100 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64 69  until the encodi
28110 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20 62 79  ng is changed by
28120 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61 74   another metadat
28130 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  a.**          in
28140 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f 72  terface call for
28150 20 74 68 65 20 73 61 6d 65 20 70 72 65 70 61 72   the same prepar
28160 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
28170 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 41   column..**.** A
28180 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
28190 2a 20 7b 41 31 33 37 35 31 7d 20 49 66 20 74 77  * {A13751} If tw
281a0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
281b0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
281c0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  re.**          [
281d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
281e0 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
281f0 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
28200 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20  nterfaces].**   
28210 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20 73         for the s
28220 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
28230 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
28240 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20  ult column.**   
28250 20 20 20 20 20 20 20 61 74 20 74 68 65 20 73 61         at the sa
28260 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
28270 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
28280 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
28290 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
282a0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
282b0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
282c0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
282d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
282e0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
282f0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
28300 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
28310 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
28320 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
28330 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
28340 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
28350 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
28360 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
28370 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
28380 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
28390 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
283a0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
283b0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
283c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
283d0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
283e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
283f0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
28400 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
28410 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
28420 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 36  ry Result {H1376
28430 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
28440 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
28450 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
28460 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
28470 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
28480 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
28490 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
284a0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
284b0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
284c0 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
284d0 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
284e0 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
284f0 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
28500 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
28510 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
28520 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
28530 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
28540 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  mn is returned. 
28550 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   If the Nth colu
28560 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
28570 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
28580 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
28590 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
285a0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
285b0 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65  urned..** The re
285c0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
285d0 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
285e0 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  coded. {END}.**.
285f0 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
28600 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
28610 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
28620 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
28630 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
28640 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
28650 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
28660 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
28670 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
28680 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
28690 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
286a0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
286b0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
286c0 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
286d0 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
286e0 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
286f0 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
28700 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
28710 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
28720 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  =0)..**.** SQLit
28730 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
28740 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
28750 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65   So just because
28760 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
28770 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
28780 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
28790 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
287a0 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
287b0 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
287c0 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
287d0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
287e0 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
287f0 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
28800 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
28810 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
28820 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a  static.  Type.**
28830 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
28840 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
28850 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
28860 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
28870 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
28880 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a  hose values..**.
28890 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
288a0 2a 0a 2a 2a 20 7b 48 31 33 37 36 31 7d 20 20 41  *.** {H13761}  A
288b0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
288c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
288d0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e  umn_decltype(S,N
288e0 29 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20  )] returns a.** 
288f0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
28900 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
28910 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
28920 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64  g the declared d
28930 61 74 61 74 79 70 65 0a 2a 2a 20 20 20 20 20 20  atatype.**      
28940 20 20 20 20 20 6f 66 20 74 68 65 20 74 61 62 6c       of the tabl
28950 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70  e column that ap
28960 70 65 61 72 73 20 61 73 20 74 68 65 20 4e 74 68  pears as the Nth
28970 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65   column (numbere
28980 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66  d.**           f
28990 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65  rom 0) of the re
289a0 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 20  sult set to the 
289b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
289c0 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ent] S..**.** {H
289d0 31 33 37 36 32 7d 20 20 41 20 73 75 63 63 65 73  13762}  A succes
289e0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
289f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
28a00 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a  ltype16(S,N)].**
28a10 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
28a20 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ns a zero-termin
28a30 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69  ated UTF-16 nati
28a40 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74  ve byte order st
28a50 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
28a60 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65    containing the
28a70 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79   declared dataty
28a80 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  pe of the table 
28a90 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65  column that appe
28aa0 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ars.**          
28ab0 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   as the Nth colu
28ac0 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f  mn (numbered fro
28ad0 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75  m 0) of the resu
28ae0 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a  lt set to the.**
28af0 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70             [prep
28b00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28b10 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 33  S..**.** {H13763
28b20 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20  }  If N is less 
28b30 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20 67  than 0 or N is g
28b40 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65  reater than or e
28b50 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20  qual to.**      
28b60 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65 72 20       the number 
28b70 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
28b80 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
28b90 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20  ement] S,.**    
28ba0 20 20 20 20 20 20 20 6f 72 20 69 66 20 74 68 65         or if the
28bb0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53   Nth column of S
28bc0 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
28bd0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 20 72 61  n or subquery ra
28be0 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
28bf0 20 20 74 68 61 6e 20 61 20 74 61 62 6c 65 20 63    than a table c
28c00 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61 20 6d  olumn, or if a m
28c10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
28c20 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20 20 20   failure.**     
28c30 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72        occurs dur
28c40 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63 6f 6e  ing encoding con
28c50 76 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a  versions, then.*
28c60 2a 20 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  *           call
28c70 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  s to [sqlite3_co
28c80 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c  lumn_decltype(S,
28c90 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  N)] or.**       
28ca0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
28cb0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53  umn_decltype16(S
28cc0 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c 4c  ,N)] return NULL
28cd0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
28ce0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
28cf0 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
28d00 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
28d10 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28d20 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
28d30 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
28d40 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
28d50 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
28d60 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
28d70 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 30  t {H13200} <S100
28d80 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  00>.**.** After 
28d90 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
28da0 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
28db0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
28dc0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
28dd0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
28de0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
28df0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
28e00 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
28e10 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
28e20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
28e30 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
28e40 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
28e50 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
28e60 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
28e70 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
28e80 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
28e90 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
28ea0 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
28eb0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
28ec0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
28ed0 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
28ee0 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
28ef0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
28f00 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
28f10 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
28f20 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
28f30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
28f40 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
28f50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
28f60 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
28f70 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
28f80 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
28f90 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
28fa0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
28fb0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
28fc0 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
28fd0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
28fe0 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
28ff0 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
29000 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
29010 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
29020 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
29030 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  orted..**.** In 
29040 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
29050 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
29060 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
29070 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
29080 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
29090 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
290a0 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
290b0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
290c0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68  MISUSE]..** With
290d0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
290e0 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
290f0 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
29100 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
29110 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
29120 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
29130 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
29140 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
29150 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
29160 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
29170 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
29180 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
29190 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
291a0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
291b0 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61  job.  If the sta
291c0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
291d0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
291e0 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
291f0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
29200 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
29210 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
29220 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
29230 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
29240 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
29250 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
29260 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74   a.** explicit t
29270 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
29280 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
29290 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
292a0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
292b0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
292c0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
292d0 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
292e0 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
292f0 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
29300 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
29310 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
29320 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
29330 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
29340 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
29350 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
29360 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
29370 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
29380 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
29390 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
293a0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
293b0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66   state..**.** If
293c0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
293d0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
293e0 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
293f0 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
29400 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
29410 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
29420 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
29430 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
29440 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
29450 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
29460 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
29470 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
29480 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
29490 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
294a0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
294b0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
294c0 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
294d0 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
294e0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  *.** [SQLITE_ERR
294f0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
29500 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
29510 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
29520 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
29530 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
29540 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
29550 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
29560 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
29570 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
29580 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
29590 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
295a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
295b0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20  msg()]..** With 
295c0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
295d0 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
295e0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
295f0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
29600 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
29610 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
29620 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
29630 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
29640 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
29650 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
29660 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
29670 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
29680 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29690 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22  ment].  In the "
296a0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
296b0 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
296c0 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
296d0 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
296e0 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
296f0 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
29700 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
29710 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
29720 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
29730 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
29740 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
29750 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
29760 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
29770 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
29780 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
29790 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
297a0 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
297b0 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
297c0 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
297d0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
297e0 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
297f0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
29800 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
29810 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
29820 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
29830 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
29840 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
29850 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
29860 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
29870 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
29880 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
29890 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
298a0 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
298b0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
298c0 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
298d0 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
298e0 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
298f0 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
29900 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
29910 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
29920 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
29930 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
29940 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
29950 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
29960 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29970 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
29980 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
29990 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
299a0 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
299b0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
299c0 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
299d0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
299e0 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
299f0 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
29a00 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
29a10 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
29a20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
29a30 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
29a40 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
29a50 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
29a60 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
29a70 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
29a80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
29a90 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
29aa0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
29ab0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
29ac0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
29ad0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
29ae0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29af0 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
29b00 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
29b10 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
29b20 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
29b30 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
29b40 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
29b50 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
29b60 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
29b70 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
29b80 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  nded..**.** INVA
29b90 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
29ba0 31 33 32 30 32 7d 20 20 49 66 20 74 68 65 20 5b  13202}  If the [
29bb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29bc0 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79 20 74  nt] S is ready t
29bd0 6f 20 62 65 20 72 75 6e 2c 20 74 68 65 6e 0a 2a  o be run, then.*
29be0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
29bf0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61 64  ite3_step(S)] ad
29c00 76 61 6e 63 65 73 20 74 68 61 74 20 70 72 65 70  vances that prep
29c10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
29c20 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ntil.**         
29c30 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20    completion or 
29c40 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61 64  until it is read
29c50 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74  y to return anot
29c60 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a  her row of the.*
29c70 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 73 75  *           resu
29c80 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e 74 69 6c  lt set, or until
29c90 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   an [sqlite3_int
29ca0 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75  errupt | interru
29cb0 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  pt].**          
29cc0 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65   or a run-time e
29cd0 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
29ce0 2a 2a 20 7b 48 31 35 33 30 34 7d 20 20 57 68 65  ** {H15304}  Whe
29cf0 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  n a call to [sql
29d00 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63 61  ite3_step(S)] ca
29d10 75 73 65 73 20 74 68 65 20 5b 70 72 65 70 61 72  uses the [prepar
29d20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
29d30 20 20 20 20 20 20 20 20 20 20 20 53 20 74 6f 20             S to 
29d40 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
29d50 6e 2c 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  n, the function 
29d60 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
29d70 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  DONE]..**.** {H1
29d80 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63 61  5306}  When a ca
29d90 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
29da0 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62 65  tep(S)] stops be
29db0 63 61 75 73 65 20 69 74 20 69 73 20 72 65 61 64  cause it is read
29dc0 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  y to.**         
29dd0 20 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72    return another
29de0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
29df0 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74 75 72  lt set, it retur
29e00 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e  ns [SQLITE_ROW].
29e10 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 38 7d 20  .**.** {H15308} 
29e20 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   If a call to [s
29e30 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
29e40 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a  encounters an.**
29e50 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
29e60 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20  te3_interrupt | 
29e70 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20  interrupt] or a 
29e80 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c 0a  run-time error,.
29e90 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 20  **           it 
29ea0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
29eb0 70 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f 64  priate error cod
29ec0 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f 6e  e that is not on
29ed0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
29ee0 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b    [SQLITE_OK], [
29ef0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72 20  SQLITE_ROW], or 
29f00 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a  [SQLITE_DONE]..*
29f10 2a 0a 2a 2a 20 7b 48 31 35 33 31 30 7d 20 20 49  *.** {H15310}  I
29f20 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e  f an [sqlite3_in
29f30 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72  terrupt | interr
29f40 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69  upt] or a run-ti
29f50 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20  me error.**     
29f60 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72        occurs dur
29f70 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
29f80 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a  qlite3_step(S)].
29f90 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f 72  **           for
29fa0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
29fb0 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65  tement] S create
29fc0 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
29fd0 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65       legacy inte
29fe0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
29ff0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a  prepare()] or.**
2a000 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
2a010 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2a020 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74  , then the funct
2a030 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68  ion returns eith
2a040 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  er.**           
2a050 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2a060 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f  [SQLITE_BUSY], o
2a070 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
2a080 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2a090 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2a0a0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2a0b0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2a0c0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2a0d0 65 73 75 6c 74 20 73 65 74 20 7b 48 31 33 37 37  esult set {H1377
2a0e0 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
2a0f0 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e 75  * Returns the nu
2a100 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69  mber of values i
2a110 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
2a120 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2a130 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  set..**.** INVAR
2a140 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
2a150 33 37 37 31 7d 20 20 41 66 74 65 72 20 61 20 63  3771}  After a c
2a160 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2a170 73 74 65 70 28 53 29 5d 20 74 68 61 74 20 72 65  step(S)] that re
2a180 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f  turns [SQLITE_RO
2a190 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  W],.**          
2a1a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61   the [sqlite3_da
2a1b0 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75  ta_count(S)] rou
2a1c0 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
2a1d0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 0a   the same value.
2a1e0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20  **           as 
2a1f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
2a200 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66 75  umn_count(S)] fu
2a210 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nction..**.** {H
2a220 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b 73  13772}  After [s
2a230 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2a240 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e 79  has returned any
2a250 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
2a260 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  n.**           [
2a270 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 62  SQLITE_ROW] or b
2a280 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
2a290 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 65 6e  tep(S)] has been
2a2a0 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 0a 2a   called on the.*
2a2b0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  *           [pre
2a2c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a2d0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 74   for the first t
2a2e0 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61 73  ime since it was
2a2f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
2a300 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
2a310 20 70 72 65 70 61 72 65 64 5d 20 6f 72 20 5b 73   prepared] or [s
2a320 71 6c 69 74 65 33 5f 72 65 73 65 74 20 7c 20 72  qlite3_reset | r
2a330 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  eset],.**       
2a340 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
2a350 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20  _data_count(S)] 
2a360 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2a370 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  zero..*/.int sql
2a380 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2a390 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2a3a0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2a3b0 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
2a3c0 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48 31  al Datatypes {H1
2a3d0 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53  0265} <S10110><S
2a3e0 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  10120>.** KEYWOR
2a3f0 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
2a400 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45  **.** {H10266} E
2a410 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
2a420 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
2a430 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
2a440 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
2a450 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
2a460 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2a470 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
2a480 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
2a490 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
2a4a0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
2a4b0 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
2a4c0 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
2a4d0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
2a4e0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
2a4f0 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
2a500 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
2a510 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2a520 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
2a530 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
2a540 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
2a550 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
2a560 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
2a570 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
2a580 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
2a590 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
2a5a0 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
2a5b0 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
2a5c0 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
2a5d0 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
2a5e0 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
2a5f0 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
2a600 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
2a610 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
2a620 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
2a630 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a640 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
2a650 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
2a660 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
2a670 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
2a680 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
2a690 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
2a6a0 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
2a6b0 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
2a6c0 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
2a6d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a6e0 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
2a6f0 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33 38  om A Query {H138
2a700 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20  00} <S10700>.** 
2a710 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
2a720 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2a730 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
2a740 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
2a750 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75  e "result set qu
2a760 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  ery" interface..
2a770 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2a780 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
2a790 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
2a7a0 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
2a7b0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
2a7c0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
2a7d0 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79  query.  In every
2a7e0 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
2a7f0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
2a800 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2a810 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a820 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
2a830 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
2a840 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
2a850 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
2a860 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
2a870 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2a880 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
2a890 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
2a8a0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
2a8b0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2a8c0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
2a8d0 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
2a8e0 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
2a8f0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54   be returned.  T
2a900 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2a910 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2a920 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
2a930 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ex 0..**.** If t
2a940 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2a950 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
2a960 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
2a970 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
2a980 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
2a990 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
2a9a0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
2a9b0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2a9c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2a9d0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
2a9e0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
2a9f0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
2aa00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2aa10 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2aa20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
2aa30 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
2aa40 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
2aa50 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2aa60 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
2aa70 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
2aa80 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
2aa90 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2aaa0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
2aab0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
2aac0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2aad0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2aae0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
2aaf0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2ab00 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
2ab10 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
2ab20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
2ab30 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2ab40 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
2ab50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2ab60 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2ab70 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2ab80 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
2ab90 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
2aba0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
2abb0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
2abc0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2abd0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
2abe0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2abf0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2ac00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2ac10 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
2ac20 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2ac30 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
2ac40 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2ac50 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
2ac60 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
2ac70 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
2ac80 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72  t column.  The r
2ac90 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
2aca0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2acb0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
2acc0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
2acd0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
2ace0 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
2acf0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
2ad00 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
2ad10 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2ad20 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2ad30 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
2ad40 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
2ad50 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
2ad60 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
2ad70 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
2ad80 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
2ad90 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
2ada0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
2adb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2adc0 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
2add0 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
2ade0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2adf0 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
2ae00 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
2ae10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2ae20 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
2ae30 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2ae40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
2ae50 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2ae60 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
2ae70 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2ae80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
2ae90 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2aea0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2aeb0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2aec0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2aed0 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
2aee0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
2aef0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2af00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2af10 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2af20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
2af30 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2af40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2af50 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ytes..** If the 
2af60 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2af70 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2af80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2af90 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
2afa0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2afb0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2afc0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2afd0 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
2afe0 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2aff0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2b000 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2b010 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   The value retur
2b020 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
2b030 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
2b040 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20  rminator at the 
2b050 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
2b060 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69  ring.  For clari
2b070 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65  ty: the value re
2b080 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75  turned is the nu
2b090 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
2b0a0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
2b0b0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
2b0c0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
2b0d0 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75  .** Strings retu
2b0e0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2b0f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
2b100 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2b110 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
2b120 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
2b130 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
2b140 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54  o terminated.  T
2b150 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2b160 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2b170 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2b180 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2b190 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74  BLOB is an arbit
2b1a0 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c  rary.** pointer,
2b1b0 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61   possibly even a
2b1c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2b1d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2b1e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2b1f0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
2b200 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  ilar to sqlite3_
2b210 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
2b220 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65  * but leaves the
2b230 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31   result in UTF-1
2b240 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  6 in native byte
2b250 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f   order instead o
2b260 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20  f UTF-8..** The 
2b270 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2b280 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20  is not included 
2b290 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a  in this count..*
2b2a0 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20  *.** The object 
2b2b0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2b2c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2b2d0 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2b2e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2b2f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2b300 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2b310 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2b320 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2b330 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2b340 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2b350 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2b360 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2b370 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2b380 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2b390 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2b3a0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2b3b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2b3c0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2b3d0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2b3e0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2b3f0 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2b400 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2b410 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2b420 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2b430 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2b440 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2b450 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2b460 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2b470 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2b480 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2b490 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2b4a0 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2b4b0 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a  propriate.  For.
2b4c0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
2b4d0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
2b4e0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
2b4f0 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
2b500 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
2b510 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
2b520 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
2b530 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
2b540 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
2b550 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
2b560 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
2b570 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
2b580 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
2b590 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
2b5a0 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
2b5b0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
2b5c0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
2b5d0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
2b5e0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
2b5f0 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
2b600 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
2b610 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
2b620 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2b630 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2b640 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2b650 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
2b660 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
2b670 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
2b680 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
2b690 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2b6a0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2b6b0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
2b6c0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2b6d0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2b6e0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2b6f0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
2b700 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2b710 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2b720 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2b730 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
2b740 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
2b750 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2b760 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
2b770 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2b780 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2b790 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
2b7a0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2b7b0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2b7c0 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
2b7d0 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
2b7e0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2b7f0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2b800 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
2b810 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
2b820 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2b830 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
2b840 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
2b850 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
2b860 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
2b870 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
2b880 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
2b890 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
2b8a0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
2b8b0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
2b8c0 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
2b8d0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
2b8e0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2b8f0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
2b900 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
2b910 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2b920 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2b930 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
2b940 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2b950 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2b960 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
2b970 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
2b980 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
2b990 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2b9a0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
2b9b0 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
2b9c0 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
2b9d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2b9e0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2b9f0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
2ba00 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
2ba10 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
2ba20 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
2ba30 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ote>.**.** The t
2ba40 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
2ba50 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
2ba60 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
2ba70 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
2ba80 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
2ba90 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
2baa0 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
2bab0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
2bac0 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
2bad0 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
2bae0 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
2baf0 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
2bb00 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
2bb10 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
2bb20 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
2bb30 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
2bb40 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
2bb50 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
2bb60 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
2bb70 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
2bb80 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
2bb90 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
2bba0 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
2bbb0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2bbc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2bbd0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
2bbe0 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
2bbf0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2bc00 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
2bc10 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
2bc20 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
2bc30 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
2bc40 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
2bc50 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
2bc60 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
2bc70 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
2bc80 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2bc90 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2bca0 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
2bcb0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2bcc0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2bcd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2bce0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2bcf0 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
2bd00 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
2bd10 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
2bd20 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
2bd30 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2bd40 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2bd50 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
2bd60 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2bd70 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
2bd80 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2bd90 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2bda0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2bdb0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2bdc0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2bdd0 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
2bde0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2bdf0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2be00 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
2be10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2be20 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
2be30 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2be40 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
2be50 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
2be60 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
2be70 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
2be80 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
2be90 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69  >.**.** Conversi
2bea0 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
2beb0 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
2bec0 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
2bed0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
2bee0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
2bef0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
2bf00 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
2bf10 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
2bf20 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
2bf30 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
2bf40 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73  r pointer points
2bf50 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65   to will have be
2bf60 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
2bf70 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
2bf80 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
2bf90 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
2bfa0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
2bfb0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
2bfc0 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
2bfd0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
2bfe0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
2bff0 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
2c000 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
2c010 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64  * The safest and
2c020 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65   easiest to reme
2c030 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74  mber policy is t
2c040 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
2c050 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
2c060 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
2c070 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
2c080 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
2c090 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2c0a0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2c0b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c0c0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2c0d0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2c0e0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
2c0f0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2c100 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2c110 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2c120 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2c130 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
2c140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c150 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
2c160 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
2c170 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
2c180 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
2c190 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
2c1a0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2c1b0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
2c1c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c1d0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
2c1e0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
2c1f0 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
2c200 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
2c210 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2c220 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2c230 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2c240 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
2c250 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
2c260 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
2c270 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
2c280 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
2c290 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
2c2a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2c2b0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
2c2c0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2c2d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
2c2e0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
2c2f0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2c300 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
2c310 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
2c320 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c330 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ytes()..**.** Th
2c340 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2c350 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
2c360 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
2c370 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
2c380 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
2c390 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
2c3a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2c3b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c3c0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2c3d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
2c3e0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65   called.  The me
2c3f0 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
2c400 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
2c410 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
2c420 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
2c430 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
2c440 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
2c450 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
2c460 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2c470 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
2c480 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2c490 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
2c4a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2c4b0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65  ]..**.** If a me
2c4c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2c4d0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2c4e0 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
2c4f0 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
2c500 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
2c510 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
2c520 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
2c530 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
2c540 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
2c550 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
2c560 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2c570 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
2c580 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
2c590 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
2c5a0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
2c5b0 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
2c5c0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
2c5d0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _NOMEM]..**.** I
2c5e0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2c5f0 20 7b 48 31 33 38 30 33 7d 20 54 68 65 20 5b 73   {H13803} The [s
2c600 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2c610 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ob(S,N)] interfa
2c620 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2c630 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
2c640 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
2c650 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2c660 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
2c670 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2c680 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c690 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 42 4c  ent] S into a BL
2c6a0 4f 42 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  OB and then retu
2c6b0 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  rns a.**        
2c6c0 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65    pointer to the
2c6d0 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65   converted value
2c6e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 36 7d  ..**.** {H13806}
2c6f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2c700 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d  lumn_bytes(S,N)]
2c710 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2c720 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
2c730 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
2c740 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f  es in the BLOB o
2c750 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  r string (exclus
2c760 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
2c770 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
2c780 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
2c790 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
2c7a0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2c7b0 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
2c7c0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2c7d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c7e0 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20  lob(S,N)] or.** 
2c7f0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2c800 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c  3_column_text(S,
2c810 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  N)]..**.** {H138
2c820 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
2c830 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c840 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2c850 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
2c860 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f          number o
2c870 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  f bytes in the s
2c880 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
2c890 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2c8a0 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
2c8b0 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
2c8c0 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
2c8d0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
2c8e0 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
2c8f0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2c900 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c910 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16(S,N)]..**.** 
2c920 7b 48 31 33 38 31 32 7d 20 54 68 65 20 5b 73 71  {H13812} The [sq
2c930 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
2c940 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ble(S,N)] interf
2c950 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2c960 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
2c970 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
2c980 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2c990 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
2c9a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c9b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c9c0 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 66  ment] S into a f
2c9d0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2c9e0 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  lue and.**      
2c9f0 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
2ca00 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65  py of that value
2ca10 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 35 7d  ..**.** {H13815}
2ca20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2ca30 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69  lumn_int(S,N)] i
2ca40 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2ca50 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2ca60 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
2ca70 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
2ca80 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2ca90 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  t for the.**    
2caa0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
2cab0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
2cac0 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65  o a 64-bit signe
2cad0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a  d integer and.**
2cae0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2caf0 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62  s the lower 32 b
2cb00 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65  its of that inte
2cb10 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  ger..**.** {H138
2cb20 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  18} The [sqlite3
2cb30 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c  _column_int64(S,
2cb40 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
2cb50 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2cb60 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2cb70 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2cb80 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2cb90 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a  lt set for the.*
2cba0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2cbb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cbc0 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  S into a 64-bit 
2cbd0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
2cbe0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
2cbf0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2cc00 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
2cc10 2a 0a 2a 2a 20 7b 48 31 33 38 32 31 7d 20 54 68  *.** {H13821} Th
2cc20 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2cc30 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 6e 74  n_text(S,N)] int
2cc40 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2cc50 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2cc60 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
2cc70 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
2cc80 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2cc90 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2cca0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2ccb0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
2ccc0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2ccd0 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20  d UTF-8.**      
2cce0 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
2ccf0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2cd00 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
2cd10 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 34 7d 20  .**.** {H13824} 
2cd20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
2cd30 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d  umn_text16(S,N)]
2cd40 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2cd50 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2cd60 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
2cd70 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
2cd80 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2cd90 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  set for the.**  
2cda0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2cdb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2cdc0 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
2cdd0 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20  nated 2-byte.** 
2cde0 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64           aligned
2cdf0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
2ce00 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67  yte order string
2ce10 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2ce20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74           a point
2ce30 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
2ce40 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 37  g..**.** {H13827
2ce50 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2ce60 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d  olumn_type(S,N)]
2ce70 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ce80 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ns.**          o
2ce90 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55  ne of [SQLITE_NU
2cea0 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54  LL], [SQLITE_INT
2ceb0 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46  EGER], [SQLITE_F
2cec0 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  LOAT],.**       
2ced0 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d     [SQLITE_TEXT]
2cee0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  , or [SQLITE_BLO
2cef0 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  B] as appropriat
2cf00 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
2cf10 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e    the Nth column
2cf20 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2cf30 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2cf40 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
2cf50 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
2cf60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2cf70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 33 30 7d  ..**.** {H13830}
2cf80 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2cf90 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d  lumn_value(S,N)]
2cfa0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2cfb0 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  ns a.**         
2cfc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
2cfd0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2cfe0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2cff0 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  t for the.**    
2d000 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
2d010 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2d020 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2d030 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
2d040 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
2d050 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2d060 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
2d070 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d080 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2d090 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2d0a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2d0b0 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
2d0c0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d0d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2d0e0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
2d0f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2d100 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
2d110 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
2d120 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2d130 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2d140 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2d150 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2d160 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
2d170 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2d180 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
2d190 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2d1a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
2d1b0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
2d1c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d1d0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
2d1e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
2d1f0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2d200 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2d210 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d220 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2d230 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2d240 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
2d250 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
2d260 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
2d270 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2d280 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d290 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
2d2a0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
2d2b0 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
2d2c0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20  tatement Object 
2d2d0 7b 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30 30  {H13300} <S70300
2d2e0 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S30100>.**.** 
2d2f0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
2d300 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
2d310 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
2d320 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
2d330 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
2d340 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2d350 77 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63  was executed suc
2d360 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74  cessfully or not
2d370 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c   executed at all
2d380 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45  , then.** SQLITE
2d390 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
2d3a0 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66   If execution of
2d3b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
2d3c0 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a  ailed then an.**
2d3d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
2d3e0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2d3f0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
2d400 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ed..**.** This r
2d410 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
2d420 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
2d430 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65  t during the exe
2d440 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  cution of the.**
2d450 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d460 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76  ment].  If the v
2d470 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68  irtual machine h
2d480 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65  as not.** comple
2d490 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68  ted execution wh
2d4a0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
2d4b0 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20  is called, that 
2d4c0 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75  is like.** encou
2d4d0 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72  ntering an error
2d4e0 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   or an [sqlite3_
2d4f0 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65  interrupt | inte
2d500 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d  rrupt]..** Incom
2d510 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61  plete updates ma
2d520 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  y be rolled back
2d530 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e   and transaction
2d540 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64  s canceled,.** d
2d550 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
2d560 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61  circumstances, a
2d570 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72  nd the.** [error
2d580 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20   code] returned 
2d590 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f  will be [SQLITE_
2d5a0 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ABORT]..**.** IN
2d5b0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2d5c0 7b 48 31 31 33 30 32 7d 20 54 68 65 20 5b 73 71  {H11302} The [sq
2d5d0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2d5e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73  )] interface des
2d5f0 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20 20  troys the.**    
2d600 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
2d610 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64  statement] S and
2d620 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a   releases all.**
2d630 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79            memory
2d640 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75 72   and file resour
2d650 63 65 73 20 68 65 6c 64 20 62 79 20 74 68 61 74  ces held by that
2d660 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b   object..**.** {
2d670 48 31 31 33 30 34 7d 20 49 66 20 74 68 65 20 6d  H11304} If the m
2d680 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2d690 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2d6a0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2d6b0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2d6c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2d6d0 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72 6f  returned an erro
2d6e0 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  r,.**          t
2d6f0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  hen [sqlite3_fin
2d700 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72 6e  alize(S)] return
2d710 73 20 74 68 61 74 20 73 61 6d 65 20 65 72 72 6f  s that same erro
2d720 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
2d730 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
2d740 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2d750 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d760 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
2d770 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2d780 65 63 74 20 7b 48 31 33 33 33 30 7d 20 3c 53 37  ect {H13330} <S7
2d790 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0300>.**.** The 
2d7a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
2d7b0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2d7c0 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
2d7d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d7e0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
2d7f0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2d800 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
2d810 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
2d820 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74  .** Any SQL stat
2d830 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
2d840 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
2d850 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
2d860 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
2d870 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2d880 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2d890 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
2d8a0 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
2d8b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
2d8c0 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
2d8d0 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
2d8e0 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33  gs..**.** {H1133
2d8f0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2d900 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2d910 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
2d920 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d930 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20  nt] S.**        
2d940 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65    back to the be
2d950 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
2d960 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  rogram..**.** {H
2d970 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f  11334} If the mo
2d980 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2d990 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2d9a0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  S)] for the.**  
2d9b0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2d9c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
2d9d0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2d9e0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
2d9f0 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  DONE],.**       
2da00 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65     or if [sqlite
2da10 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
2da20 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
2da30 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
2da40 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
2da50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2da60 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
2da70 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  E_OK]..**.** {H1
2da80 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d 6f 73  1336} If the mos
2da90 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2daa0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2dab0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  )] for the.**   
2dac0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
2dad0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2dae0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
2daf0 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
2db00 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65     [sqlite3_rese
2db10 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
2db20 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2db30 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2db40 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20 5b 73   {H11338} The [s
2db50 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2db60 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
2db70 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
2db80 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  alues.**        
2db90 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65    of any [sqlite
2dba0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
2dbb0 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
2dbc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2dbd0 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
2dbe0 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
2dbf0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2dc00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2dc10 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
2dc20 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
2dc30 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 32 30 32  s {H16100} <S202
2dc40 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
2dc50 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
2dc60 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
2dc70 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2dc80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2dc90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
2dca0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2dcb0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2dcc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
2dcd0 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20 66  *.** These two f
2dce0 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
2dcf0 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
2dd00 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
2dd10 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
2dd20 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
2dd30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
2dd40 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
2dd50 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
2dd60 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
2dd70 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
2dd80 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2dd90 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
2dda0 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 65  ifference betwee
2ddb0 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20  n the.** two is 
2ddc0 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
2ddd0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e  parameter, the n
2dde0 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c  ame of the (scal
2ddf0 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  ar) function or.
2de00 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69 73  ** aggregate, is
2de10 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
2de20 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  8 for sqlite3_cr
2de30 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
2de40 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f  and UTF-16.** fo
2de50 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2de60 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a  _function16()..*
2de70 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
2de80 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2de90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2dea0 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
2deb0 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
2dec0 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
2ded0 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65 20  d.  If a single 
2dee0 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72  program uses mor
2def0 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
2df00 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2df10 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68  n internally, th
2df20 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  en SQL functions
2df30 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20 69   must be added i
2df40 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a  ndividually to.*
2df50 2a 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  * each database 
2df60 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  connection..**.*
2df70 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
2df80 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
2df90 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
2dfa0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
2dfb0 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
2dfc0 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e 67 74  ined.  The lengt
2dfd0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
2dfe0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
2dff0 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65  bytes, exclusive
2e000 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d   of.** the zero-
2e010 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74  terminator.  Not
2e020 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20  e that the name 
2e030 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
2e040 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a  in bytes, not.**
2e050 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e   characters.  An
2e060 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
2e070 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
2e080 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
2e090 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
2e0a0 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   in [SQLITE_ERRO
2e0b0 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  R] being returne
2e0c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  d..**.** The thi
2e0d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
2e0e0 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
2e0f0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2e100 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
2e110 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2e120 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 49  gregate takes. I
2e130 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
2e140 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2e150 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
2e160 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2e170 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
2e180 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2e190 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
2e1a0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2e1b0 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
2e1c0 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
2e1d0 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
2e1e0 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
2e1f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
2e200 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
2e210 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e   parameters.  An
2e220 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  y SQL function i
2e230 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
2e240 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20  ould be able to 
2e250 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74  work.** work wit
2e260 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c  h UTF-8, UTF-16l
2e270 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20  e, or UTF-16be. 
2e280 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d   But some implem
2e290 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65  entations may be
2e2a0 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65  .** more efficie
2e2b0 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f  nt with one enco
2e2c0 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65  ding than anothe
2e2d0 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65  r.  It is allowe
2e2e0 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
2e2f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2e300 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69  nction() or sqli
2e310 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2e320 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65  ion16() multiple
2e330 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74  .** times with t
2e340 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2e350 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72   but with differ
2e360 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54  ent values of eT
2e370 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20  extRep..** When 
2e380 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2e390 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2e3a0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
2e3b0 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
2e3c0 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
2e3d0 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
2e3e0 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
2e3f0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
2e400 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49  conversion..** I
2e410 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20  f there is only 
2e420 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65  a single impleme
2e430 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f  ntation which do
2e440 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74  es not care what
2e450 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e   text.** encodin
2e460 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  g is used, then 
2e470 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
2e480 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53  ent should be [S
2e490 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
2e4a0 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72 61  * The fifth para
2e4b0 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
2e4c0 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
2e4d0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
2e4e0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e  on of the.** fun
2e4f0 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
2e500 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
2e510 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c  inter using [sql
2e520 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
2e530 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76  ]..**.** The sev
2e540 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64  enth, eighth and
2e550 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
2e560 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
2e570 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
2e580 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
2e590 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
2e5a0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
2e5b0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
2e5c0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2e5d0 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51  ate. A scalar SQ
2e5e0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
2e5f0 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
2e600 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
2e610 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
2e620 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly, NULL pointe
2e630 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  rs should be pas
2e640 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
2e650 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
2e660 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67  arameters. An ag
2e670 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2e680 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
2e690 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e6a0 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
2e6b0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
2e6c0 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
2e6d0 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64   for xFunc. To d
2e6e0 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
2e6f0 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
2e700 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
2e710 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c  pass NULL for al
2e720 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
2e730 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
2e740 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65  * It is permitte
2e750 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
2e760 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2e770 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2e780 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
2e790 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
2e7a0 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
2e7b0 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
2e7c0 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
2e7d0 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
2e7e0 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
2e7f0 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c   encodings.  SQL
2e800 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
2e810 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2e820 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  on most closely 
2e830 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
2e840 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
2e850 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2e860 75 73 65 64 2e 20 20 41 20 66 75 6e 63 74 69 6f  used.  A functio
2e870 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2e880 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
2e890 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
2e8a0 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
2e8b0 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
2e8c0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2e8d0 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
2e8e0 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
2e8f0 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65    A function whe
2e900 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
2e910 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
2e920 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
2e930 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
2e940 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
2e950 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
2e960 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
2e970 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
2e980 72 65 6e 74 2e 20 20 0a 2a 2a 20 41 20 66 75 6e  rent.  .** A fun
2e990 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2e9a0 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
2e9b0 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
2e9c0 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
2e9d0 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
2e9e0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
2e9f0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2ea00 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
2ea10 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
2ea20 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
2ea30 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69 6c 74 2d  16..**.** Built-
2ea40 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
2ea50 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
2ea60 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
2ea70 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2ea80 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ons..** The firs
2ea90 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  t application-de
2eaa0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77  fined function w
2eab0 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65  ith a given name
2eac0 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a   overrides all.*
2ead0 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74  * built-in funct
2eae0 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65  ions in the same
2eaf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2eb00 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20  ction] with the 
2eb10 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 53 75  same name..** Su
2eb20 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63 61  bsequent applica
2eb30 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2eb40 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ctions of the sa
2eb50 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65  me name only ove
2eb60 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20  rride .** prior 
2eb70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2eb80 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ned functions th
2eb90 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 74 20  at are an exact 
2eba0 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a  match for the.**
2ebb0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d   number of param
2ebc0 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 65 72  eters and prefer
2ebd0 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  red encoding..**
2ebe0 0a 2a 2a 20 41 6e 20 61 70 70 6c 69 63 61 74 69  .** An applicati
2ebf0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2ec00 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
2ec10 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
2ec20 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
2ec30 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
2ec40 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
2ec50 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
2ec60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2ec70 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
2ec80 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
2ec90 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2eca0 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
2ecb0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2ecc0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ning..**.** INVA
2ecd0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
2ece0 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  16103} The [sqli
2ecf0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ed00 69 6f 6e 31 36 28 44 2c 58 2c 2e 2e 2e 29 5d 20  ion16(D,X,...)] 
2ed10 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2ed20 62 65 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20  behave.**       
2ed30 20 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63     as [sqlite3_c
2ed40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2ed50 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 20 65 76 65 72  ,X,...)] in ever
2ed60 79 20 77 61 79 20 65 78 63 65 70 74 20 74 68 61  y way except tha
2ed70 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  t it.**         
2ed80 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
2ed90 58 20 61 72 67 75 6d 65 6e 74 20 61 73 20 7a 65  X argument as ze
2eda0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2edb0 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20  F-16.**         
2edc0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2edd0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 73  er instead of as
2ede0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2edf0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48   UTF-8..**.** {H
2ee00 31 36 31 30 36 7d 20 41 20 73 75 63 63 65 73 73  16106} A success
2ee10 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
2ee20 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2ee30 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
2ee40 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2ee50 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ,E,...)] interfa
2ee60 63 65 20 73 68 61 6c 6c 20 72 65 67 69 73 74 65  ce shall registe
2ee70 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  r.**          or
2ee80 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c 62 61   replaces callba
2ee90 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20  ck functions in 
2eea0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2eeb0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20  nnection] D.**  
2eec0 20 20 20 20 20 20 20 20 75 73 65 64 20 74 6f 20          used to 
2eed0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2eee0 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64  L function named
2eef0 20 58 20 77 69 74 68 20 4e 20 70 61 72 61 6d 65   X with N parame
2ef00 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
2ef10 20 61 6e 64 20 68 61 76 69 6e 67 20 61 20 70 72   and having a pr
2ef20 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2ef30 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a  oding of E..**.*
2ef40 2a 20 7b 48 31 36 31 30 39 7d 20 41 20 73 75 63  * {H16109} A suc
2ef50 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2ef60 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2ef70 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2ef80 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20  ,P,F,S,L)].**   
2ef90 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 70         shall rep
2efa0 6c 61 63 65 20 74 68 65 20 50 2c 20 46 2c 20 53  lace the P, F, S
2efb0 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65 73 20 66  , and L values f
2efc0 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20 63 61  rom any prior ca
2efd0 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  lls with.**     
2efe0 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 44 2c       the same D,
2eff0 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c   X, N, and E val
2f000 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  ues..**.** {H161
2f010 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
2f020 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2f030 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  (D,X,...)] inter
2f040 66 61 63 65 20 73 68 61 6c 6c 20 66 61 69 6c 0a  face shall fail.
2f050 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74  **          if t
2f060 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2f070 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20 20  name X is.**    
2f080 20 20 20 20 20 20 6c 6f 6e 67 65 72 20 74 68 61        longer tha
2f090 6e 20 32 35 35 20 62 79 74 65 73 20 65 78 63 6c  n 255 bytes excl
2f0a0 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
2f0b0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
2f0c0 0a 2a 2a 20 7b 48 31 36 31 31 38 7d 20 54 68 65  .** {H16118} The
2f0d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2f0e0 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2f0f0 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 69 6e 74 65  E,P,F,S,L)] inte
2f100 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  rface.**        
2f110 20 20 73 68 61 6c 6c 20 66 61 69 6c 20 75 6e 6c    shall fail unl
2f120 65 73 73 20 65 69 74 68 65 72 20 46 20 69 73 20  ess either F is 
2f130 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c  NULL and S and L
2f140 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72   are non-NULL or
2f150 0a 2a 2a 2a 20 20 20 20 20 20 20 20 20 46 20 69  .***         F i
2f160 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53  s non-NULL and S
2f170 20 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c 2e   and L are NULL.
2f180 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 31 7d 20  .**.** {H16121} 
2f190 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2f1a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e  ate_function(D,.
2f1b0 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  ..)] interface s
2f1c0 68 61 6c 6c 20 66 61 69 6c 73 20 77 69 74 68 20  hall fails with 
2f1d0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  an.**          e
2f1e0 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
2f1f0 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20 74 68  LITE_BUSY] if th
2f200 65 72 65 20 65 78 69 73 74 20 5b 70 72 65 70 61  ere exist [prepa
2f210 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a  red statements].
2f220 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 6f  **          asso
2f230 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2f240 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2f250 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
2f260 48 31 36 31 32 34 7d 20 54 68 65 20 5b 73 71 6c  H16124} The [sql
2f270 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f280 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
2f290 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
2f2a0 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20   fail with.**   
2f2b0 20 20 20 20 20 20 20 61 6e 20 65 72 72 6f 72 20         an error 
2f2c0 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
2f2d0 45 52 52 4f 52 5d 20 69 66 20 70 61 72 61 6d 65  ERROR] if parame
2f2e0 74 65 72 20 4e 20 69 73 20 6c 65 73 73 0a 2a 2a  ter N is less.**
2f2f0 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 2d            than -
2f300 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
2f310 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  n 127..**.** {H1
2f320 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69 73 20  6127} When N is 
2f330 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
2f340 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2f350 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2f360 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2f370 20 20 20 69 6e 74 65 72 66 61 63 65 20 73 68 61     interface sha
2f380 6c 6c 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  ll register call
2f390 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f  backs to be invo
2f3a0 6b 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  ked for the.**  
2f3b0 20 20 20 20 20 20 20 20 53 51 4c 20 66 75 6e 63          SQL func
2f3c0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
2f3d0 20 6e 61 6d 65 64 20 58 20 77 68 65 6e 20 74 68   named X when th
2f3e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
2f3f0 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c  ments to the SQL
2f400 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
2f410 20 20 20 20 20 20 20 20 20 65 78 61 63 74 6c 79           exactly
2f420 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33   N..**.** {H1613
2f430 30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d 31 2c  0} When N is -1,
2f440 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2f450 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2f460 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  X,N,...)].**    
2f470 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
2f480 73 68 61 6c 6c 20 72 65 67 69 73 74 65 72 20 63  shall register c
2f490 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69  allbacks to be i
2f4a0 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53  nvoked for the S
2f4b0 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  QL.**          f
2f4c0 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20  unction named X 
2f4d0 77 69 74 68 20 61 6e 79 20 6e 75 6d 62 65 72 20  with any number 
2f4e0 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  of arguments..**
2f4f0 0a 2a 2a 20 7b 48 31 36 31 33 33 7d 20 57 68 65  .** {H16133} Whe
2f500 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
2f510 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f520 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a  ion(D,X,N,...)].
2f530 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63  **          spec
2f540 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ify multiple imp
2f550 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2f560 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2f570 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  n X.**          
2f580 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70  and when one imp
2f590 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20  lementation has 
2f5a0 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f 74 68  N>=0 and the oth
2f5b0 65 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a  er has N=(-1).**
2f5c0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6d            the im
2f5d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
2f5e0 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 73  h a non-zero N s
2f5f0 68 61 6c 6c 20 62 65 20 70 72 65 66 65 72 72 65  hall be preferre
2f600 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 36  d..**.** {H16136
2f610 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  } When calls to 
2f620 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f630 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2f640 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2f650 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69     specify multi
2f660 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2f670 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2f680 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 0a  function X with.
2f690 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2f6a0 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20 61  same number of a
2f6b0 72 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 20 77  rguments N but w
2f6c0 69 74 68 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a  ith different.**
2f6d0 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 69            encodi
2f6e0 6e 67 73 20 45 2c 20 74 68 65 6e 20 74 68 65 20  ngs E, then the 
2f6f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2f700 68 65 72 65 20 45 20 6d 61 74 63 68 65 73 20 74  here E matches t
2f710 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  he.**          d
2f720 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
2f730 20 73 68 61 6c 6c 20 70 72 65 66 65 72 72 65 64   shall preferred
2f740 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 39 7d  ..**.** {H16139}
2f750 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67 61 74   For an aggregat
2f760 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  e SQL function c
2f770 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
2f780 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2f790 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f7a0 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c  n(D,X,N,E,P,0,S,
2f7b0 4c 29 5d 20 74 68 65 20 66 69 6e 61 6c 69 7a 65  L)] the finalize
2f7c0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  r.**          fu
2f7d0 6e 63 74 69 6f 6e 20 4c 20 73 68 61 6c 6c 20 61  nction L shall a
2f7e0 6c 77 61 79 73 20 62 65 20 69 6e 76 6f 6b 65 64  lways be invoked
2f7f0 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69 66   exactly once if
2f800 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2f810 20 73 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 53   step function S
2f820 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   is called one o
2f830 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
2f840 0a 2a 2a 20 7b 48 31 36 31 34 32 7d 20 57 68 65  .** {H16142} Whe
2f850 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
2f860 20 65 69 74 68 65 72 20 74 68 65 20 78 46 75 6e   either the xFun
2f870 63 20 6f 72 20 78 53 74 65 70 20 66 75 6e 63 74  c or xStep funct
2f880 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ion of.**       
2f890 20 20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f     an applicatio
2f8a0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2f8b0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2f8c0 61 74 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 20  ate created.**  
2f8d0 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69          by [sqli
2f8e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f8f0 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ion()] or [sqlit
2f900 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f910 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  on16()],.**     
2f920 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 61 72       then the ar
2f930 72 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ray of [sqlite3_
2f940 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20 70  value] objects p
2f950 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20  assed as the.** 
2f960 20 20 20 20 20 20 20 20 20 74 68 69 72 64 20 70           third p
2f970 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c 20 62  arameter shall b
2f980 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
2f990 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2f9a0 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  cts..*/.int sqli
2f9b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f9c0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
2f9d0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
2f9e0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2f9f0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2fa00 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2fa10 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2fa20 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2fa30 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2fa40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2fa50 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2fa60 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2fa70 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2fa80 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2fa90 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2faa0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
2fab0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2fac0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
2fad0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
2fae0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
2faf0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
2fb00 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
2fb10 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
2fb20 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
2fb30 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2fb40 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2fb50 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2fb60 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
2fb70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2fb80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2fb90 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
2fba0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
2fbb0 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  xt*).);../*.** C
2fbc0 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
2fbd0 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36 37 7d  codings {H10267}
2fbe0 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36 31 30   <S50200> <H1610
2fbf0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  0>.**.** These c
2fc00 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
2fc10 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
2fc20 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
2fc30 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
2fc40 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
2fc50 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
2fc60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2fc70 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
2fc80 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2fc90 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
2fca0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2fcb0 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
2fcc0 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
2fcd0 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
2fce0 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
2fcf0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
2fd00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2fd10 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
2fd20 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2fd30 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f  reate_function o
2fd40 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
2fd50 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
2fd60 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
2fd70 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2fd80 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
2fd90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2fda0 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
2fdb0 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
2fdc0 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
2fdd0 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
2fde0 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
2fdf0 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
2fe00 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
2fe10 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
2fe20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
2fe30 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
2fe40 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
2fe50 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
2fe60 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
2fe70 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
2fe80 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
2fe90 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
2fea0 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72    To help encour
2feb0 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76  age people to av
2fec0 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  oid.** using the
2fed0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65  se functions, we
2fee0 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74   are not going t
2fef0 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20  o tell you what 
2ff00 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e  they do..*/.#ifn
2ff10 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
2ff20 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54  DEPRECATED.SQLIT
2ff30 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2ff40 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2ff50 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
2ff60 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
2ff70 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2ff80 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
2ff90 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
2ffa0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
2ffb0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2ffc0 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
2ffd0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2ffe0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
2fff0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
30000 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  ED int sqlite3_g
30010 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
30020 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
30030 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
30040 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
30050 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  up(void);.SQLITE
30060 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
30070 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
30080 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
30090 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
300a0 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69  ,int),void*,sqli
300b0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
300c0 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
300d0 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
300e0 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
300f0 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48 31 35  eter Values {H15
30100 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  100} <S20200>.**
30110 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
30120 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
30130 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
30140 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
30150 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
30160 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
30170 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
30180 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
30190 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
301a0 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
301b0 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
301c0 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
301d0 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
301e0 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
301f0 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
30200 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
30210 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30220 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
30230 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30240 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
30250 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
30260 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
30270 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
30280 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
30290 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   The 4th paramet
302a0 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
302b0 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
302c0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
302d0 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
302e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
302f0 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
30300 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
30310 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
30320 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
30330 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
30340 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
30350 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
30360 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
30370 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
30380 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30390 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
303a0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
303b0 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
303c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
303d0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
303e0 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
303f0 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
30400 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
30410 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30420 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
30430 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
30440 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
30450 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
30460 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
30470 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
30480 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
30490 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
304a0 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
304b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
304c0 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
304d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
304e0 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
304f0 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
30500 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
30510 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
30520 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
30530 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
30540 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
30550 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
30560 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
30570 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
30580 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
30590 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
305a0 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
305b0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
305c0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
305d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
305e0 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
305f0 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
30600 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
30610 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
30620 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
30630 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
30640 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
30650 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
30660 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
30670 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
30680 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
30690 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
306a0 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
306b0 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
306c0 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
306d0 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
306e0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
306f0 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
30700 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
30710 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
30720 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
30730 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
30740 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
30750 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
30760 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
30770 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
30780 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
30790 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
307a0 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
307b0 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
307c0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
307d0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
307e0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
307f0 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
30800 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
30810 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
30820 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
30830 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
30840 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
30850 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
30860 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
30870 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
30880 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30890 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
308a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
308b0 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
308c0 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
308d0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
308e0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
308f0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
30900 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
30910 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
30920 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
30930 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
30940 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
30950 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
30960 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
30970 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
30980 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
30990 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
309a0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
309b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
309c0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a   parameters..**.
309d0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
309e0 2a 0a 2a 2a 20 7b 48 31 35 31 30 33 7d 20 54 68  *.** {H15103} Th
309f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
30a00 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72 66  _blob(V)] interf
30a10 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
30a20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
30a30 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30a40 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
30a50 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20  into a BLOB and 
30a60 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
30a70 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
30a80 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72  er to the conver
30a90 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  ted value..**.**
30aa0 20 7b 48 31 35 31 30 36 7d 20 54 68 65 20 5b 73   {H15106} The [s
30ab0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
30ac0 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  es(V)] interface
30ad0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
30ae0 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
30af0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
30b00 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28  BLOB or string (
30b10 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
30b20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
30b30 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20  o terminator on 
30b40 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74  the string) that
30b50 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79   was returned by
30b60 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30b70 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
30b80 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61  l to [sqlite3_va
30b90 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a  lue_blob(V)] or.
30ba0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
30bb0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
30bc0 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  V)]..**.** {H151
30bd0 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
30be0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 56  _value_bytes16(V
30bf0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
30c00 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
30c10 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
30c20 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
30c30 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66  ng (exclusive of
30c40 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30c50 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
30c60 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20   on the string) 
30c70 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
30c80 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
30c90 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74       most recent
30ca0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
30cb0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56  3_value_text16(V
30cc0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
30cd0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30ce0 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f 72 20  ext16be(V)], or 
30cf0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30d00 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a  ext16le(V)]..**.
30d10 2a 2a 20 7b 48 31 35 31 31 32 7d 20 54 68 65 20  ** {H15112} The 
30d20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
30d30 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65 72 66  ouble(V)] interf
30d40 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
30d50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
30d60 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30d70 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
30d80 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20  into a floating 
30d90 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a  point value and.
30da0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
30db0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
30dc0 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  at value..**.** 
30dd0 7b 48 31 35 31 31 35 7d 20 54 68 65 20 5b 73 71  {H15115} The [sq
30de0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
30df0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
30e00 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
30e10 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
30e20 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30e30 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
30e40 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
30e50 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
30e60 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74         returns t
30e70 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73  he lower 32 bits
30e80 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
30e90 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 38 7d  ..**.** {H15118}
30ea0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
30eb0 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e  lue_int64(V)] in
30ec0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
30ed0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30ee0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
30ef0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30f00 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  t V into a 64-bi
30f10 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
30f20 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
30f30 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
30f40 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
30f50 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 31 7d 20  .**.** {H15121} 
30f60 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
30f70 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e 74 65  ue_text(V)] inte
30f80 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
30f90 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
30fa0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30fb0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
30fc0 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
30fd0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
30fe0 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
30ff0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
31000 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
31010 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
31020 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  15124} The [sqli
31030 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
31040 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
31050 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
31060 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
31070 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31080 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
31090 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
310a0 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
310b0 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
310c0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
310d0 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
310e0 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
310f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
31100 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
31110 2a 0a 2a 2a 20 7b 48 31 35 31 32 37 7d 20 54 68  *.** {H15127} Th
31120 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
31130 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20 69 6e  _text16be(V)] in
31140 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
31150 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
31160 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
31170 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
31180 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  t V into a zero-
31190 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74  terminated 2-byt
311a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  e.**          al
311b0 69 67 6e 65 64 20 55 54 46 2d 31 36 20 62 69 67  igned UTF-16 big
311c0 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20  -endian.**      
311d0 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
311e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
311f0 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
31200 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 30 7d 20  .**.** {H15130} 
31210 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
31220 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 20  ue_text16le(V)] 
31230 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
31240 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
31250 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
31260 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
31270 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72  ect V into a zer
31280 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62  o-terminated 2-b
31290 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  yte.**          
312a0 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6c  aligned UTF-16 l
312b0 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20  ittle-endian.** 
312c0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
312d0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
312e0 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
312f0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ring..**.** {H15
31300 31 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  133} The [sqlite
31310 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56 29 5d  3_value_type(V)]
31320 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
31330 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ns.**          o
31340 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55  ne of [SQLITE_NU
31350 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54  LL], [SQLITE_INT
31360 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46  EGER], [SQLITE_F
31370 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  LOAT],.**       
31380 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d     [SQLITE_TEXT]
31390 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  , or [SQLITE_BLO
313a0 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  B] as appropriat
313b0 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
313c0 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    the [sqlite3_v
313d0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a  alue] object V..
313e0 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 36 7d 20 54  **.** {H15136} T
313f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
31400 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 56  e_numeric_type(V
31410 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
31420 76 65 72 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  verts.**        
31430 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64    the [protected
31440 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
31450 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 65 69  object V into ei
31460 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65 72 20  ther an integer 
31470 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  or.**          a
31480 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
31490 76 61 6c 75 65 20 69 66 20 69 74 20 63 61 6e 20  value if it can 
314a0 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f  do so without lo
314b0 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ss of.**        
314c0 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61    information, a
314d0 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f  nd returns one o
314e0 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c  f [SQLITE_NULL],
314f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
31500 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b  LITE_INTEGER], [
31510 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
31520 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72  SQLITE_TEXT], or
31530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
31540 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70  LITE_BLOB] as ap
31550 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68  propriate for th
31560 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
31570 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
31580 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
31590 20 61 66 74 65 72 20 74 68 65 20 63 6f 6e 76 65   after the conve
315a0 72 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a  rsion attempt..*
315b0 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
315c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
315d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
315e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
315f0 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
31600 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
31610 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
31620 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
31630 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  ue*);.double sql
31640 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
31650 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
31660 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
31670 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
31680 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65  _value*);.sqlite
31690 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
316a0 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
316b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
316c0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
316d0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
316e0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
316f0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
31700 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
31710 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
31720 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
31730 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
31740 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
31750 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
31760 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31770 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
31780 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31790 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
317a0 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
317b0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
317c0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
317d0 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
317e0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
317f0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
31800 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
31810 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 36 32  on Context {H162
31820 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  10} <S20200>.**.
31830 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** The implement
31840 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61  ation of aggrega
31850 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
31860 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e   use this routin
31870 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a  e to allocate.**
31880 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72   a structure for
31890 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
318a0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tate..**.** The 
318b0 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
318c0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
318d0 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69  _context() routi
318e0 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72  ne is called for
318f0 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72   a.** particular
31900 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69   aggregate, SQLi
31910 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79  te allocates nBy
31920 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  tes of memory, z
31930 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 0a 2a  eroes out that.*
31940 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  * memory, and re
31950 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
31960 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64  to it. On second
31970 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
31980 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
31990 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
319a0 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
319b0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
319c0 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a  unction index,.*
319d0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
319e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 54  r is returned. T
319f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
31a00 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  n of the aggrega
31a10 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68  te can use.** th
31a20 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65  e returned buffe
31a30 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20  r to accumulate 
31a40 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  data..**.** SQLi
31a50 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
31a60 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63   frees the alloc
31a70 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65 6e  ated buffer when
31a80 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
31a90 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  * query conclude
31aa0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
31ab0 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  st parameter sho
31ac0 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66  uld be a copy of
31ad0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
31ae0 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
31af0 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
31b00 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
31b10 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st parameter.** 
31b20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
31b30 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
31b40 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
31b50 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a  egate function..
31b60 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
31b70 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
31b80 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
31b90 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
31ba0 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
31bb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
31bc0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
31bd0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
31be0 2a 20 7b 48 31 36 32 31 31 7d 20 54 68 65 20 66  * {H16211} The f
31bf0 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  irst invocation 
31c00 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  of [sqlite3_aggr
31c10 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
31c20 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  N)] for.**      
31c30 20 20 20 20 61 20 70 61 72 74 69 63 75 6c 61 72      a particular
31c40 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 6e 20   instance of an 
31c50 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
31c60 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74 69 63  on (for a partic
31c70 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ular.**         
31c80 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61 75 73   context C) caus
31c90 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61 6c 6c  es SQLite to all
31ca0 6f 63 61 74 65 20 4e 20 62 79 74 65 73 20 6f 66  ocate N bytes of
31cb0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20 20   memory,.**     
31cc0 20 20 20 20 20 7a 65 72 6f 20 74 68 61 74 20 6d       zero that m
31cd0 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
31ce0 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  n a pointer to t
31cf0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d  he allocated mem
31d00 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  ory..**.** {H162
31d10 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79 20  13} If a memory 
31d20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
31d30 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 0a 2a   occurs during.*
31d40 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
31d50 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
31d60 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74 68 65 6e  ntext(C,N)] then
31d70 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   the function re
31d80 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b  turns 0..**.** {
31d90 48 31 36 32 31 35 7d 20 53 65 63 6f 6e 64 20 61  H16215} Second a
31da0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  nd subsequent in
31db0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20  vocations of.** 
31dc0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
31dd0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31de0 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20 74 68  ext(C,N)] for th
31df0 65 20 73 61 6d 65 20 63 6f 6e 74 65 78 74 20 70  e same context p
31e00 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20 20 20  ointer C.**     
31e10 20 20 20 20 20 69 67 6e 6f 72 65 20 74 68 65 20       ignore the 
31e20 4e 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  N parameter and 
31e30 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
31e40 20 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   to the same.** 
31e50 20 20 20 20 20 20 20 20 20 62 6c 6f 63 6b 20 6f           block o
31e60 66 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  f memory returne
31e70 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 69  d by the first i
31e80 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
31e90 20 7b 48 31 36 32 31 37 7d 20 54 68 65 20 6d 65   {H16217} The me
31ea0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
31eb0 79 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  y [sqlite3_aggre
31ec0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
31ed0 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  )] is.**        
31ee0 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20    automatically 
31ef0 66 72 65 65 64 20 6f 6e 20 74 68 65 20 6e 65 78  freed on the nex
31f00 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
31f10 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 20  e3_reset()].**  
31f20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
31f30 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
31f40 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
31f50 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e  d statement] con
31f60 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20  taining.**      
31f70 20 20 20 20 74 68 65 20 61 67 67 72 65 67 61 74      the aggregat
31f80 65 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63  e function assoc
31f90 69 61 74 65 64 20 77 69 74 68 20 63 6f 6e 74 65  iated with conte
31fa0 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  xt C..*/.void *s
31fb0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31fc0 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
31fd0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
31fe0 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
31ff0 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
32000 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
32010 20 7b 48 31 36 32 34 30 7d 20 3c 53 32 30 32 30   {H16240} <S2020
32020 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
32030 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
32040 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
32050 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
32060 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
32070 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
32080 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
32090 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
320a0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
320b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
320c0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
320d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
320e0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
320f0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
32100 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
32110 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
32120 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
32130 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ion. {END}.**.**
32140 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
32150 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
32160 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
32170 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
32180 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
32190 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
321a0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
321b0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
321c0 2a 2a 20 7b 48 31 36 32 34 33 7d 20 54 68 65 20  ** {H16243} The 
321d0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
321e0 74 61 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  ta(C)] interface
321f0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
32200 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
32210 20 20 20 50 20 70 6f 69 6e 74 65 72 20 66 72 6f     P pointer fro
32220 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  m the [sqlite3_c
32230 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
32240 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
32250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
32260 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32270 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e  function16(D,X,N
32280 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c  ,E,P,F,S,L)] cal
32290 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20  l that.**       
322a0 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68     registered th
322b0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
322c0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b  ssociated with [
322d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
322e0 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c   C..*/.void *sql
322f0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
32300 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32310 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32320 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
32330 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
32340 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c 53  ions {H16250} <S
32350 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a  60600><S20200>.*
32360 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
32370 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
32380 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
32390 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
323a0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
323b0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
323c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
323d0 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
323e0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
323f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32400 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
32410 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32420 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
32430 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
32440 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
32450 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
32460 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
32470 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ion..**.** INVAR
32480 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
32490 36 32 35 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  6253} The [sqlit
324a0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
324b0 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65 72 66 61  ndle(C)] interfa
324c0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
324d0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  y of the.**     
324e0 20 20 20 20 20 44 20 70 6f 69 6e 74 65 72 20 66       D pointer f
324f0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
32500 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32510 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
32520 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
32530 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
32540 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58  e_function16(D,X
32550 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63  ,N,E,P,F,S,L)] c
32560 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20  all that.**     
32570 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
32580 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
32590 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
325a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
325b0 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  t] C..*/.sqlite3
325c0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
325d0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
325e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
325f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32600 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
32610 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 30 7d  ry Data {H16270}
32620 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
32630 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
32640 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
32650 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
32660 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
32670 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
32680 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
32690 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
326a0 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
326b0 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
326c0 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
326d0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
326e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
326f0 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
32700 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
32710 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
32720 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
32730 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
32740 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
32750 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
32760 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
32770 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
32780 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
32790 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
327a0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
327b0 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
327c0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
327d0 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
327e0 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
327f0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
32800 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
32810 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
32820 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
32830 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
32840 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
32850 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
32860 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
32870 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
32880 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
32890 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
328a0 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
328b0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
328c0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
328d0 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
328e0 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
328f0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  on..**.** The sq
32900 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
32910 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
32920 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
32930 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
32940 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
32950 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
32960 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
32970 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
32980 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
32990 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
329a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
329b0 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65  nction. If no me
329c0 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
329d0 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74  ever.** been set
329e0 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67   for the Nth arg
329f0 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e  ument of the fun
32a00 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65  ction, or if the
32a10 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
32a20 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
32a30 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64  eter has changed
32a40 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d   since the meta-
32a50 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a  data was set,.**
32a60 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65   then sqlite3_ge
32a70 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75  t_auxdata() retu
32a80 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
32a90 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
32aa0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
32ab0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  a() interface sa
32ac0 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61  ves the metadata
32ad0 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
32ae0 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  y its 3rd parame
32af0 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64  ter as the metad
32b00 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
32b10 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
32b20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
32b30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
32b40 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a  .  Subsequent.**
32b50 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
32b60 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
32b70 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69  might return thi
32b80 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61  s data, if it ha
32b90 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65  s.** not been de
32ba0 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69  stroyed..** If i
32bb0 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  t is not NULL, S
32bc0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
32bd0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
32be0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76  .** function giv
32bf0 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61  en by the 4th pa
32c00 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
32c10 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
32c20 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64   on.** the metad
32c30 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72  ata when the cor
32c40 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
32c50 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
32c60 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e  anges.** or when
32c70 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
32c80 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68  nt completes, wh
32c90 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
32ca0 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  rst..**.** SQLit
32cb0 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c  e is free to cal
32cc0 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  l the destructor
32cd0 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61   and drop metada
32ce0 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72  ta on any.** par
32cf0 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75  ameter of any fu
32d00 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69  nction at any ti
32d10 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75  me.  The only gu
32d20 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a  arantee is that.
32d30 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ** the destructo
32d40 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  r will be called
32d50 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61   before the meta
32d60 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e  data is dropped.
32d70 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69  .**.** In practi
32d80 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
32d90 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
32da0 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
32db0 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
32dc0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
32dd0 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
32de0 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
32df0 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
32e00 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76  values and SQL v
32e10 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  ariables..**.** 
32e20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
32e30 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
32e40 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
32e50 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
32e60 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
32e70 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
32e80 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
32e90 0a 2a 2a 20 7b 48 31 36 32 37 32 7d 20 54 68 65  .** {H16272} The
32ea0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
32eb0 78 64 61 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65  xdata(C,N)] inte
32ec0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
32ed0 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
32ee0 20 20 20 20 74 6f 20 6d 65 74 61 64 61 74 61 20      to metadata 
32ef0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
32f00 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65  the Nth paramete
32f10 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  r of the SQL fun
32f20 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
32f30 20 20 77 68 6f 73 65 20 63 6f 6e 74 65 78 74 20    whose context 
32f40 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66  is C, or NULL if
32f50 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74   there is no met
32f60 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
32f70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
32f80 68 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  h that parameter
32f90 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 34 7d  ..**.** {H16274}
32fa0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
32fb0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
32fc0 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 73  D)] interface as
32fd0 73 69 67 6e 73 20 61 20 6d 65 74 61 64 61 74 61  signs a metadata
32fe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
32ff0 6e 74 65 72 20 50 20 74 6f 20 74 68 65 20 4e 74  nter P to the Nt
33000 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  h parameter of t
33010 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
33020 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a  with context C..
33030 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 36 7d 20 53  **.** {H16276} S
33040 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
33050 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
33060 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65   D with a single
33070 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
33080 20 20 20 20 20 20 77 68 69 63 68 20 69 73 20 74        which is t
33090 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69 6e  he metadata poin
330a0 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20  ter P following 
330b0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20  a call to.**    
330c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
330d0 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
330e0 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74 65  ,D)] when SQLite
330f0 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a   ceases to hold.
33100 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
33110 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20  metadata..**.** 
33120 7b 48 31 36 32 37 37 7d 20 53 51 4c 69 74 65 20  {H16277} SQLite 
33130 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d  ceases to hold m
33140 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20 53  etadata for an S
33150 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  QL function para
33160 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
33170 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75 65    when the value
33180 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65 74   of that paramet
33190 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a  er changes..**.*
331a0 2a 20 7b 48 31 36 32 37 38 7d 20 57 68 65 6e 20  * {H16278} When 
331b0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
331c0 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69  data(C,N,P,D)] i
331d0 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64  s invoked, the d
331e0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20  estructor.**    
331f0 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64 20        is called 
33200 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d 65  for any prior me
33210 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
33220 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  d with the same 
33230 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
33240 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20 61       context C a
33250 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a  nd parameter N..
33260 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 39 7d 20 53  **.** {H16279} S
33270 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20  QLite will call 
33280 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20  destructors for 
33290 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74 20  any metadata it 
332a0 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20  is holding.**   
332b0 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 72 74         in a part
332c0 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65 64  icular [prepared
332d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77 68   statement] S wh
332e0 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  en either.**    
332f0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
33300 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c  eset(S)] or [sql
33310 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
33320 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a  ] is called..*/.
33330 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
33340 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
33350 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
33360 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
33370 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
33380 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
33390 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
333a0 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
333b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
333c0 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
333d0 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
333e0 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20  ructor Behavior 
333f0 7b 48 31 30 32 38 30 7d 20 3c 53 33 30 31 30 30  {H10280} <S30100
33400 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  >.**.** These ar
33410 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73  e special values
33420 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
33430 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
33440 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
33450 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
33460 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
33470 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
33480 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65  blob()].  If the
33490 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
334a0 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
334b0 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
334c0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
334d0 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
334e0 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
334f0 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
33500 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
33510 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
33520 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c  yed.  The.** SQL
33530 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
33540 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
33550 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
33560 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
33570 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
33580 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
33590 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
335a0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
335b0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
335c0 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
335d0 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
335e0 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
335f0 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
33600 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
33610 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
33620 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
33630 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
33640 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
33650 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
33660 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
33670 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
33680 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
33690 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
336a0 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
336b0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
336c0 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
336d0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
336e0 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
336f0 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
33700 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
33710 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34  L Function {H164
33720 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  00} <S20200>.**.
33730 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
33740 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
33750 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
33760 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
33770 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
33780 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
33790 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
337a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
337b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
337c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
337d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
337e0 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
337f0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
33800 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
33810 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
33820 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
33830 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
33840 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
33850 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
33860 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
33870 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
33880 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
33890 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
338a0 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
338b0 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
338c0 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
338d0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
338e0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  n..**.** The sql
338f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
33900 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
33910 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
33920 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
33930 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33940 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
33950 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
33960 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
33970 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
33980 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
33990 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
339a0 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
339b0 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
339c0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ameter..**.** Th
339d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
339e0 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
339f0 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
33a00 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
33a10 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33a20 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
33a30 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
33a40 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
33a50 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
33a60 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
33a70 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
33a80 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
33a90 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  meter..**.** The
33aa0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33ab0 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
33ac0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
33ad0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
33ae0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33af0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
33b00 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
33b10 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
33b20 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
33b30 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
33b40 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33b50 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
33b60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33b70 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
33b80 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
33b90 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
33ba0 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
33bb0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
33bc0 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
33bd0 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
33be0 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
33bf0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
33c00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33c10 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
33c20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33c30 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
33c40 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
33c50 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e  sage.  SQLite in
33c60 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
33c70 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
33c80 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
33c90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
33ca0 20 61 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74   as UTF-8. SQLit
33cb0 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
33cc0 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
33cd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33ce0 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d  rror16() as UTF-
33cf0 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20  16 in native.** 
33d00 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20  byte order.  If 
33d10 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
33d20 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
33d30 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
33d40 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
33d50 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
33d60 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
33d70 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
33d80 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
33d90 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
33da0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
33db0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
33dc0 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69 72 64  .** If the third
33dd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
33de0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33df0 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  or() or.** sqlit
33e00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
33e10 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  6() is non-negat
33e20 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
33e30 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a  takes that many.
33e40 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ** bytes (not ch
33e50 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74  aracters) from t
33e60 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
33e70 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65   as the error me
33e80 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71  ssage..** The sq
33e90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33ea0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
33eb0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33ec0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
33ed0 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
33ee0 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
33ef0 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
33f00 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
33f10 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
33f20 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
33f30 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
33f40 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
33f50 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
33f60 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
33f70 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  arm..** The sqli
33f80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33f90 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
33fa0 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
33fb0 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
33fc0 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
33fd0 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
33fe0 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
33ff0 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ion.  By default
34000 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
34010 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
34020 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71 75 65  ROR.  A subseque
34030 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
34040 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
34050 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
34060 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
34070 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f   resets the erro
34080 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45  r code to SQLITE
34090 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68  _ERROR..**.** Th
340a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
340b0 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
340c0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
340d0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
340e0 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
340f0 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
34100 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f  or BLOB is to lo
34110 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ng to represent.
34120 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
34130 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28  e3_result_nomem(
34140 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
34150 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
34160 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
34170 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
34180 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
34190 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
341a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
341b0 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
341c0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
341d0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
341e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
341f0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34200 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
34210 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
34220 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
34230 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
34240 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ent..** The sqli
34250 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
34260 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
34270 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
34280 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
34290 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
342a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
342b0 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
342c0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
342d0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
342e0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
342f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
34300 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
34310 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
34320 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
34330 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
34340 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34350 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
34360 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
34370 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
34380 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
34390 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
343a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
343b0 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
343c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
343d0 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
343e0 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
343f0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
34400 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34410 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
34420 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
34430 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
34440 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
34450 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
34460 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
34470 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
34480 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
34490 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
344a0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51  pectively..** SQ
344b0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
344c0 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
344d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
344e0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
344f0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
34500 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34510 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
34520 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
34530 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
34540 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34550 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
34560 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
34570 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
34580 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
34590 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
345a0 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
345b0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
345c0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66  character..** If
345d0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
345e0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
345f0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
34600 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
34610 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
34620 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
34630 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
34640 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
34650 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
34660 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
34670 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
34680 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
34690 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
346a0 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  n result..** If 
346b0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
346c0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
346d0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
346e0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
346f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
34700 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
34710 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
34720 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
34730 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
34740 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
34750 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
34760 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
34770 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
34780 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
34790 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34  ult..** If the 4
347a0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
347b0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
347c0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
347d0 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ces or.** sqlite
347e0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
347f0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
34800 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
34810 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
34820 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
34830 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
34840 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
34850 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
34860 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
34870 70 79 20 74 68 65 20 69 74 20 6f 72 20 63 61 6c  py the it or cal
34880 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 77  l a destructor w
34890 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
348a0 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
348b0 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
348c0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
348d0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
348e0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
348f0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
34900 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
34910 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
34920 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
34930 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
34940 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
34950 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
34960 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
34970 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
34980 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
34990 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
349a0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
349b0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
349c0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
349d0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
349e0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
349f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34a00 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
34a10 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
34a20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
34a30 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34a40 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
34a50 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
34a60 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  r.  The.** sqlit
34a70 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
34a80 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
34a90 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
34aa0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
34ab0 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
34ac0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
34ad0 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
34ae0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
34af0 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
34b00 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
34b10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
34b20 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
34b30 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
34b40 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  A [protected sql
34b50 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34b60 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65  ct may always be
34b70 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a   used where an.*
34b80 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
34b90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34ba0 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64  ject is required
34bb0 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b  , so either.** k
34bc0 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ind of [sqlite3_
34bd0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61  value] object ca
34be0 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74  n be used with t
34bf0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  his interface..*
34c00 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f  *.** If these ro
34c10 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
34c20 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68  d from within th
34c30 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  e different thre
34c40 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f  ad.** than the o
34c50 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ne containing th
34c60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
34c70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
34c80 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20  hat received.** 
34c90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
34ca0 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74  text] pointer, t
34cb0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
34cc0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
34cd0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
34ce0 2a 20 7b 48 31 36 34 30 33 7d 20 54 68 65 20 64  * {H16403} The d
34cf0 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20 76 61  efault return va
34d00 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c  lue from any SQL
34d10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c   function is NUL
34d20 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 36  L..**.** {H16406
34d30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
34d40 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
34d50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
34d60 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
34d70 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
34d80 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
34d90 43 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 74  C to be a BLOB t
34da0 68 61 74 20 69 73 20 4e 20 62 79 74 65 73 0a 2a  hat is N bytes.*
34db0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 6c 65  *          in le
34dc0 6e 67 74 68 20 61 6e 64 20 77 69 74 68 20 63 6f  ngth and with co
34dd0 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f  ntent pointed to
34de0 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   by V..**.** {H1
34df0 36 34 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  6409} The [sqlit
34e00 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
34e10 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
34e20 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
34e30 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
34e40 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
34e50 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 66 6c  n C to be the fl
34e60 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
34e70 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ue V..**.** {H16
34e80 34 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  412} The [sqlite
34e90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 43  3_result_error(C
34ea0 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,V,N)] interface
34eb0 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
34ec0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
34ed0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
34ee0 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
34ef0 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
34f00 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
34f10 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
34f20 5d 20 61 6e 64 20 61 20 55 54 46 2d 38 20 65 72  ] and a UTF-8 er
34f30 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f 70 69  ror message copi
34f40 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20  ed from V up to 
34f50 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
34f60 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74 65 20  first zero byte 
34f70 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73  or until N bytes
34f80 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69   are read if N i
34f90 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a  s positive..**.*
34fa0 2a 20 7b 48 31 36 34 31 35 7d 20 54 68 65 20 5b  * {H16415} The [
34fb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34fc0 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69  rror16(C,V,N)] i
34fd0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
34fe0 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
34ff0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
35000 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
35010 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77  e an exception w
35020 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  ith error code.*
35030 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
35040 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20  TE_ERROR] and a 
35050 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
35060 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72 20 6d  te order error m
35070 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20  essage.**       
35080 20 20 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56     copied from V
35090 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
350a0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
350b0 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65   or until N byte
350c0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  s.**          ar
350d0 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70  e read if N is p
350e0 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  ositive..**.** {
350f0 48 31 36 34 31 38 7d 20 54 68 65 20 5b 73 71 6c  H16418} The [sql
35100 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35110 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74  r_toobig(C)] int
35120 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
35130 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  he return.**    
35140 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74        value of t
35150 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  he function C to
35160 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
35170 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
35180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
35190 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64  LITE_TOOBIG] and
351a0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
351b0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
351c0 2a 0a 2a 2a 20 7b 48 31 36 34 32 31 7d 20 54 68  *.** {H16421} Th
351d0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
351e0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29  t_error_nomem(C)
351f0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
35200 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
35210 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
35220 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
35230 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
35240 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
35250 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
35260 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
35270 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69   and an appropri
35280 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ate error messag
35290 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 34  e..**.** {H16424
352a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
352b0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
352c0 28 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,E)] interface
352d0 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
352e0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
352f0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
35300 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
35310 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
35320 65 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a  error code E..**
35330 20 20 20 20 20 20 20 20 20 20 54 68 65 20 65 72            The er
35340 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
35350 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
35360 2a 0a 2a 2a 20 7b 48 31 36 34 32 37 7d 20 54 68  *.** {H16427} Th
35370 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
35380 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65  t_int(C,V)] inte
35390 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
353a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
353b0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
353c0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
353d0 68 65 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65  he 32-bit intege
353e0 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  r value V..**.**
353f0 20 7b 48 31 36 34 33 30 7d 20 54 68 65 20 5b 73   {H16430} The [s
35400 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
35410 74 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 72 66  t64(C,V)] interf
35420 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
35430 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
35440 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
35450 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
35460 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
35470 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  value V..**.** {
35480 48 31 36 34 33 33 7d 20 54 68 65 20 5b 73 71 6c  H16433} The [sql
35490 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
354a0 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (C)] interface c
354b0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
354c0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
354d0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
354e0 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  C to be NULL..**
354f0 0a 2a 2a 20 7b 48 31 36 34 33 36 7d 20 54 68 65  .** {H16436} The
35500 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
35510 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20  _text(C,V,N,D)] 
35520 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
35530 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
35540 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
35550 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
35560 62 65 20 74 68 65 20 55 54 46 2d 38 20 73 74 72  be the UTF-8 str
35570 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
35580 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
35590 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e  t zero if N is n
355a0 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  egative.**      
355b0 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74      or the first
355c0 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
355d0 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
355e0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33  ve..**.** {H1643
355f0 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
35600 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c  result_text16(C,
35610 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
35620 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
35630 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
35640 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
35650 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55  on C to be the U
35660 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
35670 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
35680 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20      string V up 
35690 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
356a0 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  o if N is negati
356b0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ve.**          o
356c0 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
356d0 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73  tes of V if N is
356e0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
356f0 2a 0a 2a 2a 20 7b 48 31 36 34 34 32 7d 20 54 68  *.** {H16442} Th
35700 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
35710 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
35720 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
35730 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
35740 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
35750 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
35760 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
35770 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a  16 big-endian.**
35780 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
35790 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
357a0 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20  st zero if N is 
357b0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
357c0 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73       or the firs
357d0 74 20 4e 20 62 79 74 65 73 20 6f 72 20 56 20 69  t N bytes or V i
357e0 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
357f0 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ive..**.** {H164
35800 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  45} The [sqlite3
35810 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
35820 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
35830 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
35840 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
35850 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
35860 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
35870 65 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d  e UTF-16 little-
35880 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
35890 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74     string V up t
358a0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
358b0 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
358c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  e.**          or
358d0 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74   the first N byt
358e0 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20  es of V if N is 
358f0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a  non-negative..**
35900 0a 2a 2a 20 7b 48 31 36 34 34 38 7d 20 54 68 65  .** {H16448} The
35910 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
35920 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74  _value(C,V)] int
35930 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
35940 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
35950 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
35960 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
35970 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
35980 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
35990 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65  **          obje
359a0 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ct V..**.** {H16
359b0 34 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  451} The [sqlite
359c0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
359d0 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  b(C,N)] interfac
359e0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
359f0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
35a00 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
35a10 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d  on C to be an N-
35a20 62 79 74 65 20 42 4c 4f 42 20 6f 66 20 61 6c 6c  byte BLOB of all
35a30 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48   zeros..**.** {H
35a40 31 36 34 35 34 7d 20 54 68 65 20 5b 73 71 6c 69  16454} The [sqli
35a50 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35a60 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
35a70 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
35a80 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
35a90 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 20 61  nterfaces make a
35aa0 20 63 6f 70 79 20 6f 66 20 74 68 65 69 72 20 65   copy of their e
35ab0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
35ac0 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20  ings before.**  
35ad0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 69 6e          returnin
35ae0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 37  g..**.** {H16457
35af0 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
35b00 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
35b10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
35b20 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
35b30 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
35b40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35b50 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
35b60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35b70 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
35b80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
35b90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35ba0 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
35bb0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
35bc0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35bd0 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
35be0 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61  )] is the consta
35bf0 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  nt [SQLITE_STATI
35c00 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  C].**          t
35c10 68 65 6e 20 6e 6f 20 64 65 73 74 72 75 63 74 6f  hen no destructo
35c20 72 20 69 73 20 65 76 65 72 20 63 61 6c 6c 65 64  r is ever called
35c30 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65 72 20   on the pointer 
35c40 56 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20  V and SQLite.** 
35c50 20 20 20 20 20 20 20 20 20 61 73 73 75 6d 65 73           assumes
35c60 20 74 68 61 74 20 56 20 69 73 20 69 6d 6d 75 74   that V is immut
35c70 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  able..**.** {H16
35c80 34 36 30 7d 20 49 66 20 74 68 65 20 44 20 64 65  460} If the D de
35c90 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
35ca0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
35cb0 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
35cc0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
35cd0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
35ce0 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
35cf0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
35d00 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
35d10 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
35d20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35d30 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
35d40 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
35d50 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
35d60 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
35d70 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e  N,D)] is the con
35d80 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  stant.**        
35d90 20 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49    [SQLITE_TRANSI
35da0 45 4e 54 5d 20 74 68 65 6e 20 74 68 65 20 69 6e  ENT] then the in
35db0 74 65 72 66 61 63 65 73 20 6d 61 6b 65 73 20 61  terfaces makes a
35dc0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
35dd0 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 6e 74           content
35de0 20 6f 66 20 56 20 61 6e 64 20 72 65 74 61 69 6e   of V and retain
35df0 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a  s the copy..**.*
35e00 2a 20 7b 48 31 36 34 36 33 7d 20 49 66 20 74 68  * {H16463} If th
35e10 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70  e D destructor p
35e20 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
35e30 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
35e40 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
35e50 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
35e60 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
35e70 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ,N,D)], [sqlite3
35e80 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43  _result_text16(C
35e90 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
35ea0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
35eb0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43  esult_text16be(C
35ec0 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,N,D)], or.** 
35ed0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
35ee0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
35ef0 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73  e(C,V,N,D)] is s
35f00 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68 65 72 20  ome value other 
35f10 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
35f20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b   the constants [
35f30 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 20 61  SQLITE_STATIC] a
35f40 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  nd [SQLITE_TRANS
35f50 49 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a 20 20 20  IENT] then.**   
35f60 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 77 69         SQLite wi
35f70 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
35f80 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20  structor D with 
35f90 56 20 61 73 20 69 74 73 20 6f 6e 6c 79 20 61 72  V as its only ar
35fa0 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  gument.**       
35fb0 20 20 20 77 68 65 6e 20 69 74 20 68 61 73 20 66     when it has f
35fc0 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
35fd0 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69   V value..*/.voi
35fe0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35ff0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  _blob(sqlite3_co
36000 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
36010 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
36020 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
36030 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
36040 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  ouble(sqlite3_co
36050 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b  ntext*, double);
36060 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36070 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74  sult_error(sqlit
36080 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
36090 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a  st char*, int);.
360a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
360b0 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69  ult_error16(sqli
360c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
360d0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  nst void*, int);
360e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
360f0 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
36100 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
36110 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
36120 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
36130 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e  omem(sqlite3_con
36140 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
36150 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36160 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63  r_code(sqlite3_c
36170 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
36180 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36190 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63  lt_int(sqlite3_c
361a0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
361b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
361c0 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  lt_int64(sqlite3
361d0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
361e0 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  e3_int64);.void 
361f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
36200 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ull(sqlite3_cont
36210 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
36220 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
36230 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36240 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
36250 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
36260 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
36270 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
36280 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36290 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
362a0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
362b0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
362c0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
362d0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
362e0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
362f0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
36300 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
36310 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
36320 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
36330 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
36340 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
36350 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
36360 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
36370 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36380 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
36390 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
363a0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
363b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
363c0 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  *, int n);../*.*
363d0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69  * CAPI3REF: Defi
363e0 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67  ne New Collating
363f0 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31 36 36   Sequences {H166
36400 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a  00} <S20300>.**.
36410 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
36420 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ns are used to a
36430 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  dd new collation
36440 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68   sequences to th
36450 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
36460 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
36470 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
36480 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
36490 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
364a0 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  e new collation 
364b0 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63  sequence is spec
364c0 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38  ified as a UTF-8
364d0 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
364e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
364f0 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
36500 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36510 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
36520 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
36530 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ng for sqlite3_c
36540 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
36550 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65  6(). In all case
36560 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73  s.** the name is
36570 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
36580 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
36590 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
365a0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
365b0 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  t may be one of 
365c0 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
365d0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
365e0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
365f0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
36600 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6BE], indicating
36610 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73   that the user-s
36620 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69  upplied.** routi
36630 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65  ne expects to be
36640 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73   passed pointers
36650 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f   to strings enco
36660 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c  ded using UTF-8,
36670 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
36680 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e-endian, or UTF
36690 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20  -16 big-endian, 
366a0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 54 68  respectively. Th
366b0 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d  e.** third argum
366c0 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62  ent might also b
366d0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
366e0 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69  ALIGNED] to indi
366f0 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  cate that.** the
36700 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
36710 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d   pointers to 16-
36720 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64  bit word aligned
36730 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55   strings.** of U
36740 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
36750 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 6f  ive byte order o
36760 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75  f the host compu
36770 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  ter..**.** A poi
36780 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72  nter to the user
36790 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e   supplied routin
367a0 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  e must be passed
367b0 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a   as the fifth.**
367c0 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 69   argument.  If i
367d0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20  t is NULL, this 
367e0 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64  is the same as d
367f0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c  eleting the coll
36800 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
36810 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74  e (so that SQLit
36820 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74  e cannot call it
36830 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61   anymore)..** Ea
36840 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c  ch time the appl
36850 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64  ication supplied
36860 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
36870 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73  oked, it is pass
36880 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72  ed.** as its fir
36890 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20 63  st parameter a c
368a0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
368b0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
368c0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
368d0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  * to sqlite3_cre
368e0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
368f0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
36900 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
36910 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  .**.** The remai
36920 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74  ning arguments t
36930 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
36940 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  n-supplied routi
36950 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e  ne are two strin
36960 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72  gs,.** each repr
36970 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65  esented by a (le
36980 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72  ngth, data) pair
36990 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20   and encoded in 
369a0 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  the encoding.** 
369b0 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20  that was passed 
369c0 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  as the third arg
369d0 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63  ument when the c
369e0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
369f0 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65  e was.** registe
36a00 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20  red. {END}  The 
36a10 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
36a20 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f  ned collation ro
36a30 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20  utine should.** 
36a40 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c  return negative,
36a50 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76   zero or positiv
36a60 65 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  e if the first s
36a70 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
36a80 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c  an,.** equal to,
36a90 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
36aa0 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69   the second stri
36ab0 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47  ng. i.e. (STRING
36ac0 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a  1 - STRING2)..**
36ad0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
36ae0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36af0 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
36b00 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36b10 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65  collation().** e
36b20 78 63 65 70 74 20 74 68 61 74 20 69 74 20 74 61  xcept that it ta
36b30 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67  kes an extra arg
36b40 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
36b50 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a   destructor for.
36b60 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  ** the collation
36b70 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
36b80 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e  r is called when
36b90 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
36ba0 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61  s.** destroyed a
36bb0 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63  nd is passed a c
36bc0 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74  opy of the fourt
36bd0 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64  h parameter void
36be0 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20  * pointer.** of 
36bf0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
36c00 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
36c10 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73  )..** Collations
36c20 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77   are destroyed w
36c30 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
36c40 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
36c50 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
36c60 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
36c70 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
36c80 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62   when the [datab
36c90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36ca0 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69  is closed.** usi
36cb0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
36cc0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  e()]..**.** INVA
36cd0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
36ce0 31 36 36 30 33 7d 20 41 20 73 75 63 63 65 73 73  16603} A success
36cf0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a  ful call to the.
36d00 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
36d10 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36d20 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
36d30 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,D)] interface
36d40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
36d50 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f 6e 20  isters function 
36d60 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61 72 69  F as the compari
36d70 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73 65  son function use
36d80 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  d to.**         
36d90 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61   implement colla
36da0 74 69 6f 6e 20 58 20 6f 6e 20 74 68 65 20 5b 64  tion X on the [d
36db0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36dc0 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20  on] B for.**    
36dd0 20 20 20 20 20 20 64 61 74 61 62 61 73 65 73 20        databases 
36de0 68 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20  having encoding 
36df0 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 34  E..**.** {H16604
36e00 7d 20 53 51 4c 69 74 65 20 75 6e 64 65 72 73 74  } SQLite underst
36e10 61 6e 64 73 20 74 68 65 20 58 20 70 61 72 61 6d  ands the X param
36e20 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eter to.**      
36e30 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65      [sqlite3_cre
36e40 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
36e50 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61  (B,X,E,P,F,D)] a
36e60 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
36e70 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
36e80 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 20  UTF-8 string in 
36e90 77 68 69 63 68 20 63 61 73 65 20 69 73 20 69 67  which case is ig
36ea0 6e 6f 72 65 64 20 66 6f 72 20 41 53 43 49 49 20  nored for ASCII 
36eb0 63 68 61 72 61 63 74 65 72 73 20 61 6e 64 0a 2a  characters and.*
36ec0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 73 69  *          is si
36ed0 67 6e 69 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f  gnificant for no
36ee0 6e 2d 41 53 43 49 49 20 63 68 61 72 61 63 74 65  n-ASCII characte
36ef0 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30  rs..**.** {H1660
36f00 36 7d 20 53 75 63 63 65 73 73 69 76 65 20 63 61  6} Successive ca
36f10 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
36f20 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36f30 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
36f40 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
36f50 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  th the same valu
36f60 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64  es for B, X, and
36f70 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70 72 69   E, override pri
36f80 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  or values.**    
36f90 20 20 20 20 20 20 6f 66 20 50 2c 20 46 2c 20 61        of P, F, a
36fa0 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  nd D..**.** {H16
36fb0 36 30 39 7d 20 49 66 20 74 68 65 20 64 65 73 74  609} If the dest
36fc0 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c  ructor D in [sql
36fd0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36fe0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
36ff0 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
37000 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74     is not NULL t
37010 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c 65 64  hen it is called
37020 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
37030 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   when the.**    
37040 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
37050 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
37060 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ped by SQLite..*
37070 2a 0a 2a 2a 20 7b 48 31 36 36 31 32 7d 20 41 20  *.** {H16612} A 
37080 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37090 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68  on is dropped wh
370a0 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c 6f 61  en it is overloa
370b0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  ded..**.** {H166
370c0 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  15} A collating 
370d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
370e0 70 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74  ped when the dat
370f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37100 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
37110 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
37120 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
37130 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 38 7d 20 54  **.** {H16618} T
37140 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69 6e 20  he pointer P in 
37150 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
37160 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
37170 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20  ,E,P,F,D)].**   
37180 20 20 20 20 20 20 20 69 73 20 70 61 73 73 65 64         is passed
37190 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
371a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
371b0 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f  to the compariso
371c0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  n.**          fu
371d0 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c  nction F for all
371e0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
371f0 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a  cations of F..**
37200 0a 2a 2a 20 7b 48 31 36 36 32 31 7d 20 41 20 63  .** {H16621} A c
37210 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
37220 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
37230 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20  (B,X,E,P,F)] is 
37240 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20  exactly.**      
37250 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20      the same as 
37260 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
37270 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37280 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a  ion_v2()] with.*
37290 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
372a0 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  ame parameters a
372b0 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 72 75  nd a NULL destru
372c0 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ctor..**.** {H16
372d0 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61  624} Following a
372e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
372f0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
37300 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20  X,E,P,F,D)],.** 
37310 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20           SQLite 
37320 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61 72 69  uses the compari
37330 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 20 66  son function F f
37340 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70  or all text comp
37350 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  arison.**       
37360 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e     operations on
37370 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
37380 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20  onnection] B on 
37390 74 65 78 74 20 76 61 6c 75 65 73 20 74 68 61 74  text values that
373a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65  .**          use
373b0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73   the collating s
373c0 65 71 75 65 6e 63 65 20 6e 61 6d 65 64 20 58 2e  equence named X.
373d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 37 7d 20  .**.** {H16627} 
373e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
373f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
37400 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b  B,X,E,P,F)] work
37410 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  s the same.**   
37420 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c 69 74         as [sqlit
37430 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37440 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20  ion(B,X,E,P,F)] 
37450 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 0a  except that the.
37460 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c  **          coll
37470 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20  ation name X is 
37480 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20 55 54  understood as UT
37490 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62  F-16 in native b
374a0 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20  yte order.**    
374b0 20 20 20 20 20 20 69 6e 73 74 65 61 64 20 6f 66        instead of
374c0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48   UTF-8..**.** {H
374d0 31 36 36 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74  16630} When mult
374e0 69 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20  iple comparison 
374f0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 76  functions are av
37500 61 69 6c 61 62 6c 65 20 66 6f 72 20 74 68 65 20  ailable for the 
37510 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
37520 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
37530 6e 63 65 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f  nce, SQLite choo
37540 73 65 73 20 74 68 65 20 6f 6e 65 20 77 68 6f 73  ses the one whos
37550 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  e text encoding.
37560 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 71 75  **          requ
37570 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  ires the least a
37580 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73  mount of convers
37590 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64 65 66  ion from the def
375a0 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ault.**         
375b0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f   text encoding o
375c0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  f the database..
375d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
375e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
375f0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
37600 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
37610 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
37620 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
37630 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
37640 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37650 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37660 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
37670 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37680 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
37690 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
376a0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
376b0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
376c0 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
376d0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
376e0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
376f0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
37700 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
37710 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  )(void*).);.int 
37720 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37730 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
37740 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
37750 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
37760 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
37770 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
37780 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
37790 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
377a0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
377b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
377c0 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
377d0 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b  eded Callbacks {
377e0 48 31 36 37 30 30 7d 20 3c 53 32 30 33 30 30 3e  H16700} <S20300>
377f0 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  .**.** To avoid 
37800 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
37810 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
37820 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
37830 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
37840 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
37850 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
37860 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
37870 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
37880 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
37890 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
378a0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65  e called wheneve
378b0 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
378c0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
378d0 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64  ence is required
378e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
378f0 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
37900 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
37910 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
37920 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
37930 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
37940 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
37950 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
37960 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
37970 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
37980 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
37990 7b 48 31 36 37 30 33 7d 20 49 66 20 73 71 6c 69  {H16703} If sqli
379a0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
379b0 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64  eded16() is used
379c0 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61  ,.** the names a
379d0 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46  re passed as UTF
379e0 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e  -16 in machine n
379f0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
37a00 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 65  ..** A call to e
37a10 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
37a20 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73  eplaces any exis
37a30 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  ting callback..*
37a40 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
37a50 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
37a60 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
37a70 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
37a80 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
37a90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
37aa0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
37ab0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
37ac0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
37ad0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
37ae0 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
37af0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
37b00 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
37b10 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
37b20 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
37b30 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
37b40 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
37b50 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
37b60 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
37b70 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
37b80 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
37b90 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
37ba0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
37bb0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
37bc0 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
37bd0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
37be0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
37bf0 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
37c00 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20  sequence..**.** 
37c10 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
37c20 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
37c30 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
37c40 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
37c50 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
37c60 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
37c70 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
37c80 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
37c90 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
37ca0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37cb0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  on_v2()]..**.** 
37cc0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
37cd0 2a 20 7b 48 31 36 37 30 32 7d 20 41 20 73 75 63  * {H16702} A suc
37ce0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
37cf0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
37d00 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c 46 29  on_needed(D,P,F)
37d10 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
37d20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
37d30 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44 2c 50  ion_needed16(D,P
37d40 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20  ,F)] causes.**  
37d50 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 61 74          the [dat
37d60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37d70 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61  ] D to invoke ca
37d80 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20 66 69  llback F with fi
37d90 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rst.**          
37da0 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e  parameter P when
37db0 65 76 65 72 20 69 74 20 6e 65 65 64 73 20 61 20  ever it needs a 
37dc0 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
37dd0 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20  ion for a.**    
37de0 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
37df0 73 65 71 75 65 6e 63 65 20 74 68 61 74 20 69 74  sequence that it
37e00 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61   does not know a
37e10 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  bout..**.** {H16
37e20 37 30 34 7d 20 45 61 63 68 20 73 75 63 63 65 73  704} Each succes
37e30 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
37e40 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
37e50 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20  needed()] or.** 
37e60 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
37e70 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37e80 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69 64 65  ed16()] override
37e90 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  s the callback r
37ea0 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20  egistered.**    
37eb0 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d        on the sam
37ec0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37ed0 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72  ection] by prior
37ee0 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68 65 72   calls to either
37ef0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
37f00 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  erface..**.** {H
37f10 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d 65 20  16706} The name 
37f20 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  of the requested
37f30 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37f40 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20 74 68  ion passed in th
37f50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 34 74  e.**          4t
37f60 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
37f70 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
37f80 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65 20 63  n UTF-8 if the c
37f90 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
37fa0 20 20 20 20 77 61 73 20 72 65 67 69 73 74 65 72      was register
37fb0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
37fc0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37fd0 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ed()] and.**    
37fe0 20 20 20 20 20 20 69 73 20 69 6e 20 55 54 46 2d        is in UTF-
37ff0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
38000 72 64 65 72 20 69 66 20 74 68 65 20 63 61 6c 6c  rder if the call
38010 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20  back was.**     
38020 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
38030 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
38040 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
38050 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
38060 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
38070 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33  eeded(.  sqlite3
38080 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20  *, .  void*, .  
38090 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
380a0 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
380b0 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  Rep,const char*)
380c0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
380d0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
380e0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
380f0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64  .  void*,.  void
38100 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
38110 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
38120 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
38130 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
38140 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e  he key for an en
38150 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65  crypted database
38160 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
38170 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c  should be.** cal
38180 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20  led right after 
38190 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
381a0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
381b0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
381c0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
381d0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
381e0 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
381f0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
38200 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20   sqlite3_key(.  
38210 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
38220 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
38230 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
38240 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
38250 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
38260 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
38270 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  The key */.);../
38280 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20  *.** Change the 
38290 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64  key on an open d
382a0 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65  atabase.  If the
382b0 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73   current databas
382c0 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72  e is not.** encr
382d0 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74  ypted, this rout
382e0 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74  ine will encrypt
382f0 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30   it.  If pNew==0
38300 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65   or nNew==0, the
38310 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20  .** database is 
38320 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a  decrypted..**.**
38330 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
38340 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
38350 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
38360 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
38370 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
38380 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
38390 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c  te3_rekey(.  sql
383a0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
383b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
383c0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
383d0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
383e0 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
383f0 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
38400 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   new key */.);..
38410 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38420 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f  Suspend Executio
38430 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69  n For A Short Ti
38440 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53 34 30  me {H10530} <S40
38450 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  410>.**.** The s
38460 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66  qlite3_sleep() f
38470 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
38480 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
38490 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
384a0 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74  cution.** for at
384b0 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20   least a number 
384c0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
384d0 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73  specified in its
384e0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
384f0 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69  * If the operati
38500 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
38510 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
38520 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a   requests with.*
38530 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
38540 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
38550 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
38560 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
38570 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  to.** the neares
38580 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75  t second. The nu
38590 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
385a0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
385b0 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
385c0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
385d0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
385e0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
385f0 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e   SQLite implemen
38600 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
38610 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
38620 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
38630 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
38640 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
38650 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
38660 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
38670 20 7b 48 31 30 35 33 33 7d 20 54 68 65 20 5b 73   {H10533} The [s
38680 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d  qlite3_sleep(M)]
38690 20 69 6e 74 65 72 66 61 63 65 20 69 6e 76 6f 6b   interface invok
386a0 65 73 20 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a  es the xSleep.**
386b0 20 20 20 20 20 20 20 20 20 20 6d 65 74 68 6f 64            method
386c0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
386d0 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c 56 46 53  [sqlite3_vfs|VFS
386e0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ] in order to.**
386f0 20 20 20 20 20 20 20 20 20 20 73 75 73 70 65 6e            suspen
38700 64 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  d execution of t
38710 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
38720 64 20 66 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a  d for at least.*
38730 2a 20 20 20 20 20 20 20 20 20 20 4d 20 6d 69 6c  *          M mil
38740 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a  liseconds..**.**
38750 20 7b 48 31 30 35 33 36 7d 20 54 68 65 20 5b 73   {H10536} The [s
38760 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d  qlite3_sleep(M)]
38770 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
38780 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
38790 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 69 6c  .**          mil
387a0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
387b0 65 70 20 61 63 74 75 61 6c 6c 79 20 72 65 71 75  ep actually requ
387c0 65 73 74 65 64 20 6f 66 20 74 68 65 20 6f 70 65  ested of the ope
387d0 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  rating.**       
387e0 20 20 20 73 79 73 74 65 6d 2c 20 77 68 69 63 68     system, which
387f0 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72   might be larger
38800 20 74 68 61 6e 20 74 68 65 20 70 61 72 61 6d 65   than the parame
38810 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ter M..*/.int sq
38820 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29  lite3_sleep(int)
38830 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38840 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  F: Name Of The F
38850 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
38860 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 48  mporary Files {H
38870 31 30 33 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a  10310} <S20000>.
38880 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c  **.** If this gl
38890 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
388a0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
388b0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
388c0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
388d0 6