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

Artifact 5853e42a4066a6c9c3bf6592a9d57d0012bfdb90:


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 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 20 7b 48 31 30 30 31 30 7d 20 3c 53 36 30  rs {H10010} <S60
0ac0: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  100>.**.** The S
0ad0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 61 6e  QLITE_VERSION an
0ae0: 64 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  d SQLITE_VERSION
0af0: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 73  _NUMBER #defines
0b00: 20 69 6e 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74   in.** the sqlit
0b10: 65 33 2e 68 20 66 69 6c 65 20 73 70 65 63 69 66  e3.h file specif
0b20: 79 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f 66  y the version of
0b30: 20 53 51 4c 69 74 65 20 77 69 74 68 20 77 68 69   SQLite with whi
0b40: 63 68 0a 2a 2a 20 74 68 61 74 20 68 65 61 64 65  ch.** that heade
0b50: 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63 69  r file is associ
0b60: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
0b70: 22 76 65 72 73 69 6f 6e 22 20 6f 66 20 53 51 4c  "version" of SQL
0b80: 69 74 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  ite is a string 
0b90: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 57 2e 58  of the form "W.X
0ba0: 2e 59 22 20 6f 72 20 22 57 2e 58 2e 59 2e 5a 22  .Y" or "W.X.Y.Z"
0bb0: 2e 0a 2a 2a 20 54 68 65 20 57 20 76 61 6c 75 65  ..** The W value
0bc0: 20 69 73 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f   is major versio
0bd0: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 69 73 20  n number and is 
0be0: 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69  always 3 in SQLi
0bf0: 74 65 33 2e 0a 2a 2a 20 54 68 65 20 57 20 76 61  te3..** The W va
0c00: 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73  lue only changes
0c10: 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64 73 20   when backwards 
0c20: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73  compatibility is
0c30: 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77  .** broken and w
0c40: 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65  e intend to neve
0c50: 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61 72 64  r break backward
0c60: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
0c70: 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20  .** The X value 
0c80: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72  is the minor ver
0c90: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20  sion number and 
0ca0: 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65  only changes whe
0cb0: 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d  n.** there are m
0cc0: 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68  ajor feature enh
0cd0: 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61  ancements that a
0ce0: 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70  re forwards comp
0cf0: 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f  atible.** but no
0d00: 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  t backwards comp
0d10: 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 59  atible..** The Y
0d20: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 72 65   value is the re
0d30: 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61 6e 64  lease number and
0d40: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20   is incremented 
0d50: 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c  with.** each rel
0d60: 65 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20  ease but resets 
0d70: 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 65 76  back to 0 whenev
0d80: 65 72 20 58 20 69 73 20 69 6e 63 72 65 6d 65 6e  er X is incremen
0d90: 74 65 64 2e 0a 2a 2a 20 54 68 65 20 5a 20 76 61  ted..** The Z va
0da0: 6c 75 65 20 6f 6e 6c 79 20 61 70 70 65 61 72 73  lue only appears
0db0: 20 6f 6e 20 62 72 61 6e 63 68 20 72 65 6c 65 61   on branch relea
0dc0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ses..**.** The S
0dd0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0de0: 4d 42 45 52 20 69 73 20 61 6e 20 69 6e 74 65 67  MBER is an integ
0df0: 65 72 20 74 68 61 74 20 69 73 20 63 6f 6d 70 75  er that is compu
0e00: 74 65 64 20 61 73 0a 2a 2a 20 66 6f 6c 6c 6f 77  ted as.** follow
0e10: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
0e20: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 53 51  uote><pre>.** SQ
0e30: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
0e40: 42 45 52 20 3d 20 57 2a 31 30 30 30 30 30 30 20  BER = W*1000000 
0e50: 2b 20 58 2a 31 30 30 30 20 2b 20 59 0a 2a 2a 20  + X*1000 + Y.** 
0e60: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
0e70: 74 65 3e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20  te>.**.** Since 
0e80: 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20  version 3.6.18, 
0e90: 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f  SQLite source co
0ea0: 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72  de has been stor
0eb0: 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20  ed in the.** <a 
0ec0: 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77  href="http://www
0ed0: 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f  .fossil-scm.org/
0ee0: 22 3e 66 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75  ">fossil configu
0ef0: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e  ration managemen
0f00: 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e  t.** system</a>.
0f10: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55    The SQLITE_SOU
0f20: 52 43 45 5f 49 44 0a 2a 2a 20 6d 61 63 72 6f 20  RCE_ID.** macro 
0f30: 69 73 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  is a string whic
0f40: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0f50: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0f60: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0f70: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0f80: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0f90: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ent system.  The
0fa0: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73   string contains
0fb0: 20 74 68 65 0a 2a 2a 20 64 61 74 65 20 61 6e 64   the.** date and
0fc0: 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65   time of the che
0fd0: 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20  ck-in (UTC) and 
0fe0: 61 6e 20 53 48 41 31 20 68 61 73 68 20 6f 66 20  an SHA1 hash of 
0ff0: 74 68 65 20 65 6e 74 69 72 65 0a 2a 2a 20 73 6f  the entire.** so
1000: 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a  urce tree..**.**
1010: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1020: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1030: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ],.** [sqlite3_l
1040: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1050: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f  ()], [sqlite3_so
1060: 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73  urceid()],.** [s
1070: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d  qlite_version()]
1080: 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75   and [sqlite_sou
1090: 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rce_id()]..**.**
10a0: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
10b0: 48 31 30 30 31 31 5d 20 5b 48 31 30 30 31 34 5d  H10011] [H10014]
10c0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
10d0: 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20  TE_VERSION      
10e0: 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65    "--VERS--".#de
10f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
1100: 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52  ION_NUMBER --VER
1110: 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64  SION-NUMBER--.#d
1120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55  efine SQLITE_SOU
1130: 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53  RCE_ID      "--S
1140: 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a  OURCE-ID--"../*.
1150: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1160: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
1170: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48  rsion Numbers {H
1180: 31 30 30 32 30 7d 20 3c 53 36 30 31 30 30 3e 0a  10020} <S60100>.
1190: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
11a0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a  ite3_version.**.
11b0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61  ** These interfa
11c0: 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20  ces provide the 
11d0: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
11e0: 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   as the [SQLITE_
11f0: 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51  VERSION],.** [SQ
1200: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1210: 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  BER], and [SQLIT
1220: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 23 64 65  E_SOURCE_ID] #de
1230: 66 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61  fines in the hea
1240: 64 65 72 2c 0a 2a 2a 20 62 75 74 20 61 72 65 20  der,.** but are 
1250: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1260: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
1270: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
1280: 72 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75  r file.  Cautiou
1290: 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73  s.** programmers
12a0: 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61   might include a
12b0: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
12c0: 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ts in their appl
12d0: 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65  ication to.** ve
12e0: 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73  rify that values
12f0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1300: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  se interfaces ma
1310: 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69  tch the macros i
1320: 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c  n.** the header,
1330: 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65   and thus insure
1340: 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63   that the applic
1350: 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70  ation is.** comp
1360: 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69  iled with matchi
1370: 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68  ng library and h
1380: 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a  eader files..**.
1390: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
13a0: 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20  pre>.** assert( 
13b0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
13c0: 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c  on_number()==SQL
13d0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
13e0: 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  ER );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1400: 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54  sourceid(),SQLIT
1410: 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20  E_SOURCE_ID)==0 
1420: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
1430: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62  rcmp(sqlite3_lib
1440: 76 65 72 73 69 6f 6e 2c 53 51 4c 49 54 45 5f 56  version,SQLITE_V
1450: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
1460: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1470: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ote>.**.** The s
1480: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1490: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
14a0: 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20 69 6e  urns the same in
14b0: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a  formation as is.
14c0: 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ** in the sqlite
14d0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
14e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68  ng constant.  Th
14f0: 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  e function is pr
1500: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73  ovided.** for us
1510: 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20  e in DLLs since 
1520: 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c  DLL users usuall
1530: 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 64 69  y do not have di
1540: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
1550: 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e  tring.** constan
1560: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c  ts within the DL
1570: 4c 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 74  L.  Similarly, t
1580: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1590: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  eid() function.*
15a0: 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 61  * returns the sa
15b0: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
15c0: 73 20 69 73 20 69 6e 20 74 68 65 20 5b 53 51 4c  s is in the [SQL
15d0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 23  ITE_SOURCE_ID] #
15e0: 64 65 66 69 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  define of.** the
15f0: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2a   header file..**
1600: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1610: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d  qlite_version()]
1620: 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75   and [sqlite_sou
1630: 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rce_id()]..**.**
1640: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
1650: 48 31 30 30 32 31 5d 20 5b 48 31 30 30 32 32 5d  H10021] [H10022]
1660: 20 5b 48 31 30 30 32 33 5d 0a 2a 2f 0a 53 51 4c   [H10023].*/.SQL
1670: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
1680: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
1690: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
16a0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
16b0: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63  version(void);.c
16c0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
16d0: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
16e0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
16f0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1700: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1710: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f  API3REF: Test To
1720: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72   See If The Libr
1730: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66  ary Is Threadsaf
1740: 65 20 7b 48 31 30 31 30 30 7d 20 3c 53 36 30 31  e {H10100} <S601
1750: 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  00>.**.** SQLite
1760: 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64   can be compiled
1770: 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74   with or without
1780: 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a   mutexes.  When.
1790: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
17a0: 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 65  HREADSAFE] C pre
17b0: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
17c0: 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78  is 1 or 2, mutex
17d0: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
17e0: 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20  d and SQLite is 
17f0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 65  threadsafe.  Whe
1800: 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  n the.** [SQLITE
1810: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63  _THREADSAFE] mac
1820: 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65  ro is 0, .** the
1830: 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69   mutexes are omi
1840: 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74  tted.  Without t
1850: 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69  he mutexes, it i
1860: 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f  s not safe.** to
1870: 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63   use SQLite conc
1880: 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f  urrently from mo
1890: 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65  re than one thre
18a0: 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69  ad..**.** Enabli
18b0: 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72  ng mutexes incur
18c0: 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70  s a measurable p
18d0: 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c  erformance penal
18e0: 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65  ty..** So if spe
18f0: 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20  ed is of utmost 
1900: 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d  importance, it m
1910: 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69  akes sense to di
1920: 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74  sable.** the mut
1930: 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d  exes.  But for m
1940: 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d  aximum safety, m
1950: 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65  utexes should be
1960: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65   enabled..** The
1970: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
1980: 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73  r is for mutexes
1990: 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a   to be enabled..
19a0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
19b0: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
19c0: 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69   by an applicati
19d0: 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  on to make sure 
19e0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73  that the.** vers
19f0: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68  ion of SQLite th
1a00: 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67  at it is linking
1a10: 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d   against was com
1a20: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
1a30: 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e  e desired settin
1a40: 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  g of the [SQLITE
1a50: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63  _THREADSAFE] mac
1a60: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ro..**.** This i
1a70: 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65  nterface only re
1a80: 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d  ports on the com
1a90: 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20  pile-time mutex 
1aa0: 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68  setting.** of th
1ab0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1ac0: 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20  SAFE] flag.  If 
1ad0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
1ae0: 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54  ed with.** SQLIT
1af0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 74  E_THREADSAFE=1 t
1b00: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
1b10: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
1b20: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
1b30: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
1b40: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
1b50: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
1b60: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
1b70: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
1b80: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
1b90: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
1ba0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
1bb0: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
1bc0: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
1bd0: 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20 72  G_MUTEX].  The r
1be0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1bf0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
1c00: 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20 64  ws.** only the d
1c10: 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d 74  efault compile-t
1c20: 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f 74  ime setting, not
1c30: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68   any run-time ch
1c40: 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61 74  anges.** to that
1c50: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
1c60: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  See the [threadi
1c70: 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e  ng mode] documen
1c80: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
1c90: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
1ca0: 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  n..**.** Require
1cb0: 6d 65 6e 74 73 3a 20 5b 48 31 30 31 30 31 5d 20  ments: [H10101] 
1cc0: 5b 48 31 30 31 30 32 5d 0a 2a 2f 0a 69 6e 74 20  [H10102].*/.int 
1cd0: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1ce0: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  fe(void);../*.**
1cf0: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
1d00: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48  ase Connection H
1d10: 61 6e 64 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c  andle {H12000} <
1d20: 53 34 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S40200>.** KEYWO
1d30: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63  RDS: {database c
1d40: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61  onnection} {data
1d50: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1d60: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65  }.**.** Each ope
1d70: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
1d80: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  e is represented
1d90: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   by a pointer to
1da0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a   an instance of.
1db0: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74  ** the opaque st
1dc0: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73  ructure named "s
1dd0: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20  qlite3".  It is 
1de0: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20  useful to think 
1df0: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a  of an sqlite3.**
1e00: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f   pointer as an o
1e10: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c  bject.  The [sql
1e20: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1e30: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1e40: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1e50: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
1e60: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20  erfaces are its 
1e70: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e  constructors, an
1e80: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
1e90: 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65  ()].** is its de
1ea0: 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65  structor.  There
1eb0: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20   are many other 
1ec0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
1ed0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
1ee0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
1ef0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
1f00: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
1f10: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
1f20: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
1f30: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
1f40: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
1f50: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
1f60: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
1f70: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
1f80: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
1f90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
1fa0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
1fb0: 73 20 7b 48 31 30 32 30 30 7d 20 3c 53 31 30 31  s {H10200} <S101
1fc0: 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  10>.** KEYWORDS:
1fd0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
1fe0: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
1ff0: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2000: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2010: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2020: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2030: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2040: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2050: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
2060: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
2070: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
2080: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2090: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
20a0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
20b0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
20c0: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
20d0: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
20e0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
20f0: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2100: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2110: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2120: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2130: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
2140: 5b 48 31 30 32 30 31 5d 20 5b 48 31 30 32 30 32  [H10201] [H10202
2150: 5d 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ].*/.#ifdef SQLI
2160: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  TE_INT64_TYPE.  
2170: 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49  typedef SQLITE_I
2180: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2190: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
21a0: 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54  f unsigned SQLIT
21b0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
21c0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69  ite_uint64;.#eli
21d0: 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56  f defined(_MSC_V
21e0: 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f  ER) || defined(_
21f0: 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74  _BORLANDC__).  t
2200: 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73  ypedef __int64 s
2210: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
2220: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2230: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  __int64 sqlite_u
2240: 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74  int64;.#else.  t
2250: 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67  ypedef long long
2260: 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36   int sqlite_int6
2270: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2280: 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20  igned long long 
2290: 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  int sqlite_uint6
22a0: 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65  4;.#endif.typede
22b0: 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  f sqlite_int64 s
22c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79  qlite3_int64;.ty
22d0: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e  pedef sqlite_uin
22e0: 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  t64 sqlite3_uint
22f0: 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f  64;../*.** If co
2300: 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72  mpiling for a pr
2310: 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63  ocessor that lac
2320: 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  ks floating poin
2330: 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75  t support,.** su
2340: 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72  bstitute integer
2350: 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f   for floating-po
2360: 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  int..*/.#ifdef S
2370: 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54  QLITE_OMIT_FLOAT
2380: 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69  ING_POINT.# defi
2390: 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  ne double sqlite
23a0: 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a  3_int64.#endif..
23b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23c0: 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61  Closing A Databa
23d0: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48  se Connection {H
23e0: 31 32 30 31 30 7d 20 3c 53 33 30 31 30 30 3e 3c  12010} <S30100><
23f0: 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40200>.**.** Th
2400: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68  is routine is th
2410: 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  e destructor for
2420: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2430: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  bject..**.** App
2440: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b  lications must [
2450: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2460: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2470: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2480: 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ments].** and [s
2490: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
24a0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
24b0: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73  BLOB handles] as
24c0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
24d0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
24e0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
24f0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2500: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a  se the object..*
2510: 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  *.** If [sqlite3
2520: 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76  _close()] is inv
2530: 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61  oked while a tra
2540: 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nsaction is open
2550: 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63  ,.** the transac
2560: 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69  tion is automati
2570: 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
2580: 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70  k..**.** The C p
2590: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
25a0: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d  ite3_close(C)] m
25b0: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
25c0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
25d0: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
25e0: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
25f0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
2600: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
2610: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
2620: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
2630: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
2640: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
2650: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  sly closed..**.*
2660: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
2670: 2a 2a 20 5b 48 31 32 30 31 31 5d 20 5b 48 31 32  ** [H12011] [H12
2680: 30 31 32 5d 20 5b 48 31 32 30 31 33 5d 20 5b 48  012] [H12013] [H
2690: 31 32 30 31 34 5d 20 5b 48 31 32 30 31 35 5d 20  12014] [H12015] 
26a0: 5b 48 31 32 30 31 39 5d 0a 2a 2f 0a 69 6e 74 20  [H12019].*/.int 
26b0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71  sqlite3_close(sq
26c0: 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  lite3 *);../*.**
26d0: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
26e0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
26f0: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
2700: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
2710: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
2720: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
2730: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
2740: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
2750: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
2760: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
2770: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
2780: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
2790: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
27a0: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
27b0: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
27c0: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 7b 48  ion Interface {H
27d0: 31 32 31 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a  12100} <S10000>.
27e0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27f0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
2800: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
2810: 6e 74 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e  nt way of runnin
2820: 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  g one or more.**
2830: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
2840: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
2850: 6f 20 77 72 69 74 65 20 61 20 6c 6f 74 20 6f 66  o write a lot of
2860: 20 43 20 63 6f 64 65 2e 20 20 54 68 65 20 55 54   C code.  The UT
2870: 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 53  F-8 encoded.** S
2880: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
2890: 65 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  e passed in as t
28a0: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
28b0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
28c0: 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 74  xec()..** The st
28d0: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61  atements are eva
28e0: 6c 75 61 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e  luated one by on
28f0: 65 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61  e until either a
2900: 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a 20 61 6e  n error or.** an
2910: 20 69 6e 74 65 72 72 75 70 74 20 69 73 20 65 6e   interrupt is en
2920: 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72 20 75 6e  countered, or un
2930: 74 69 6c 20 74 68 65 79 20 61 72 65 20 61 6c 6c  til they are all
2940: 20 64 6f 6e 65 2e 20 20 54 68 65 20 33 72 64 20   done.  The 3rd 
2950: 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20  parameter.** is 
2960: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63 61 6c 6c  an optional call
2970: 62 61 63 6b 20 74 68 61 74 20 69 73 20 69 6e 76  back that is inv
2980: 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  oked once for ea
2990: 63 68 20 72 6f 77 20 6f 66 20 61 6e 79 20 71 75  ch row of any qu
29a0: 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74 73 20 70  ery.** results p
29b0: 72 6f 64 75 63 65 64 20 62 79 20 74 68 65 20 53  roduced by the S
29c0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
29d0: 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
29e0: 72 20 74 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a  r tells where.**
29f0: 20 74 6f 20 77 72 69 74 65 20 61 6e 79 20 65 72   to write any er
2a00: 72 6f 72 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a  ror messages..**
2a10: 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72 20 6d 65  .** The error me
2a20: 73 73 61 67 65 20 70 61 73 73 65 64 20 62 61 63  ssage passed bac
2a30: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
2a40: 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 68  h parameter is h
2a50: 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79  eld.** in memory
2a60: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2a70: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2a80: 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20 61 20 6d  ].  To avoid a m
2a90: 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74  emory leak,.** t
2aa0: 68 65 20 63 61 6c 6c 69 6e 67 20 61 70 70 6c 69  he calling appli
2ab0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 63 61  cation should ca
2ac0: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
2ad0: 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72 72 6f 72  ()] on any error
2ae0: 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72 65 74 75  .** message retu
2af0: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
2b00: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 77   5th parameter w
2b10: 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
2b20: 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hed using.** the
2b30: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
2b40: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
2b50: 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
2b60: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2b70: 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d  is NULL or an em
2b80: 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a 20 6f 72  pty string.** or
2b90: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69   a string contai
2ba0: 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69 74 65 73  ning only whites
2bb0: 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  pace and comment
2bc0: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 0a 2a  s, then no SQL.*
2bd0: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  * statements are
2be0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
2bf0: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  he database is n
2c00: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a  ot changed..**.*
2c10: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
2c20: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ec() interface i
2c30: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e  s implemented in
2c40: 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71   terms of.** [sq
2c50: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c60: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2c70: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2c80: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
2c90: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2ca0: 65 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64  exec() routine d
2cb0: 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74  oes nothing to t
2cc0: 68 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74  he database that
2cd0: 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a   cannot be done.
2ce0: 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
2cf0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
2d00: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
2d10: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
2d20: 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  alize()]..**.** 
2d30: 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2d40: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
2d50: 65 78 65 63 28 29 5d 20 6d 75 73 74 20 62 65 20  exec()] must be 
2d60: 61 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65  an valid and ope
2d70: 6e 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  n.** [database c
2d80: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a  onnection]..**.*
2d90: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63  * The database c
2da0: 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
2db0: 6f 74 20 62 65 20 63 6c 6f 73 65 64 20 77 68 69  ot be closed whi
2dc0: 6c 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  le.** [sqlite3_e
2dd0: 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  xec()] is runnin
2de0: 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  g..**.** The cal
2df0: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
2e00: 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65  ould use [sqlite
2e10: 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65  3_free()] to fre
2e20: 65 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  e.** the memory 
2e30: 74 68 61 74 20 2a 65 72 72 6d 73 67 20 69 73 20  that *errmsg is 
2e40: 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 61 74  left pointing at
2e50: 20 6f 6e 63 65 20 74 68 65 20 65 72 72 6f 72 0a   once the error.
2e60: 2a 2a 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f  ** message is no
2e70: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
2e80: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 20 73 74  **.** The SQL st
2e90: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 20  atement text in 
2ea0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2eb0: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  r to [sqlite3_ex
2ec0: 65 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 72 65  ec()].** must re
2ed0: 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77  main unchanged w
2ee0: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78  hile [sqlite3_ex
2ef0: 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  ec()] is running
2f00: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
2f10: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 31 30 31  ents:.** [H12101
2f20: 5d 20 5b 48 31 32 31 30 32 5d 20 5b 48 31 32 31  ] [H12102] [H121
2f30: 30 34 5d 20 5b 48 31 32 31 30 35 5d 20 5b 48 31  04] [H12105] [H1
2f40: 32 31 30 37 5d 20 5b 48 31 32 31 31 30 5d 20 5b  2107] [H12110] [
2f50: 48 31 32 31 31 33 5d 20 5b 48 31 32 31 31 36 5d  H12113] [H12116]
2f60: 0a 2a 2a 20 5b 48 31 32 31 31 39 5d 20 5b 48 31  .** [H12119] [H1
2f70: 32 31 32 32 5d 20 5b 48 31 32 31 32 35 5d 20 5b  2122] [H12125] [
2f80: 48 31 32 31 33 31 5d 20 5b 48 31 32 31 33 34 5d  H12131] [H12134]
2f90: 20 5b 48 31 32 31 33 37 5d 20 5b 48 31 32 31 33   [H12137] [H1213
2fa0: 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  8].*/.int sqlite
2fb0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  3_exec(.  sqlite
2fc0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
2fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fe0: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
2ff0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
3000: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst char *sql,  
3010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3020: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20           /* SQL 
3030: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
3040: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
3050: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
3060: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
3070: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
3080: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
3090: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
30a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30b0: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
30c0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
30d0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
30e0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
30f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3100: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
3110: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
3120: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
3130: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b  : Result Codes {
3140: 48 31 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e  H10210} <S10700>
3150: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
3160: 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63  LITE_OK {error c
3170: 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65  ode} {error code
3180: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
3190: 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72  {result code} {r
31a0: 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a  esult codes}.**.
31b0: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
31c0: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
31d0: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
31e0: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
31f0: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
3200: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
3210: 64 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20  dicates success 
3220: 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  or failure..**.*
3230: 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65  * New error code
3240: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
3250: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
3260: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
3270: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51  ** See also: [SQ
3280: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
3290: 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  | extended resul
32a0: 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66  t codes].*/.#def
32b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
32c0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
32d0: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
32e0: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
32f0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
3300: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3310: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
3320: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
3330: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
3340: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
3350: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
3360: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
3370: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
3380: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
3390: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
33a0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
33b0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
33c0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
33d0: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
33e0: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
33f0: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
3400: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
3410: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
3420: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
3430: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
3440: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
3450: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
3460: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
3470: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
3480: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
3490: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
34a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
34b0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
34c0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
34d0: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
34e0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
34f0: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
3500: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
3510: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
3520: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3530: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
3540: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
3550: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
3560: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
3570: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3580: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
3590: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
35a0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
35b0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
35c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
35d0: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
35e0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
35f0: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
3600: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
3610: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
3620: 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20      12   /* NOT 
3630: 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72  USED. Table or r
3640: 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20  ecord not found 
3650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3660: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33  E_FULL        13
3670: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20     /* Insertion 
3680: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64  failed because d
3690: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20  atabase is full 
36a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
36b0: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34  E_CANTOPEN    14
36c0: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20     /* Unable to 
36d0: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
36e0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
36f0: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f  e SQLITE_PROTOCO
3700: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54  L    15   /* NOT
3710: 20 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20   USED. Database 
3720: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
3730: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
3740: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
3750: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61    16   /* Databa
3760: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23  se is empty */.#
3770: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
3780: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
3790: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
37a0: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
37b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37c0: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
37d0: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
37e0: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
37f0: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
3800: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
3810: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
3820: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
3830: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
3840: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3850: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
3860: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
3870: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
3880: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
3890: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
38a0: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
38b0: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
38c0: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
38d0: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
38e0: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
38f0: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
3900: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
3910: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
3920: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
3930: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
3940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3950: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
3960: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61   /* Auxiliary da
3970: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72  tabase format er
3980: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
3990: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20  QLITE_RANGE     
39a0: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61    25   /* 2nd pa
39b0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
39c0: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72  e3_bind out of r
39d0: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ange */.#define 
39e0: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20  SQLITE_NOTADB   
39f0: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20     26   /* File 
3a00: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e  opened that is n
3a10: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
3a20: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
3a30: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
3a40: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
3a50: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
3a60: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
3a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3a80: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
3a90: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
3aa0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
3ab0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
3ac0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
3ad0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
3ae0: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
3af0: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31  Result Codes {H1
3b00: 30 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  0220} <S10700>.*
3b10: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
3b20: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
3b30: 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  } {extended erro
3b40: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3b50: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
3b60: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78  result code} {ex
3b70: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
3b80: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74  des}.**.** In it
3b90: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  s default config
3ba0: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  uration, SQLite 
3bb0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74  API routines ret
3bc0: 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e  urn one of 26 in
3bd0: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  teger.** [SQLITE
3be0: 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  _OK | result cod
3bf0: 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65  es].  However, e
3c00: 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68  xperience has sh
3c10: 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66  own that many of
3c20: 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74  .** these result
3c30: 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63   codes are too c
3c40: 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20  oarse-grained.  
3c50: 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76  They do not prov
3c60: 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69  ide as.** much i
3c70: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
3c80: 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f   problems as pro
3c90: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c  grammers might l
3ca0: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f  ike.  In an effo
3cb0: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73  rt to.** address
3cc0: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72   this, newer ver
3cd0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
3ce0: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61  (version 3.3.8 a
3cf0: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
3d00: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
3d10: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
3d20: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
3d30: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
3d40: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
3d50: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
3d60: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65   The extended re
3d70: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65  sult codes are e
3d80: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
3d90: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64  ed.** on a per d
3da0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3db0: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74  on basis using t
3dc0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
3dd0: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
3de0: 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a  odes()] API..**.
3df0: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61  ** Some of the a
3e00: 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65  vailable extende
3e10: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
3e20: 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a  re listed here..
3e30: 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63  ** One may expec
3e40: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
3e50: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
3e60: 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78  codes will be ex
3e70: 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d  pand.** over tim
3e80: 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  e.  Software tha
3e90: 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20  t uses extended 
3ea0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f  result codes sho
3eb0: 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f  uld expect.** to
3ec0: 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20   see new result 
3ed0: 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20  codes in future 
3ee0: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
3ef0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  te..**.** The SQ
3f00: 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63  LITE_OK result c
3f10: 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62  ode will never b
3f20: 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20  e extended.  It 
3f30: 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62  will always.** b
3f40: 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a  e exactly zero..
3f50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3f60: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20  E_IOERR_READ    
3f70: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3f80: 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29  E_IOERR | (1<<8)
3f90: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3fa0: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
3fb0: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
3fc0: 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29  _IOERR | (2<<8))
3fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fe0: 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20  IOERR_WRITE     
3ff0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4000: 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a  IOERR | (3<<8)).
4010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4020: 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20  OERR_FSYNC      
4030: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4040: 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OERR | (4<<8)).#
4050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4060: 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20  ERR_DIR_FSYNC   
4070: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4080: 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64  ERR | (5<<8)).#d
4090: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
40a0: 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20  RR_TRUNCATE     
40b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
40c0: 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  RR | (6<<8)).#de
40d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
40e0: 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20  R_FSTAT         
40f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4100: 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66  R | (7<<8)).#def
4110: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4120: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _UNLOCK         
4130: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4140: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
4150: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4160: 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  RDLOCK          
4170: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4180: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
4190: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
41a0: 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
41b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
41c0: 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (10<<8)).#defin
41d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42  e SQLITE_IOERR_B
41e0: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20  LOCKED          
41f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4200: 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (11<<8)).#defin
4210: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e  e SQLITE_IOERR_N
4220: 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20  OMEM            
4230: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4240: 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (12<<8)).#defin
4250: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41  e SQLITE_IOERR_A
4260: 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20  CCESS           
4270: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4280: 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (13<<8)).#defin
4290: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
42a0: 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b  HECKRESERVEDLOCK
42b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
42c0: 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (14<<8)).#defin
42d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c  e SQLITE_IOERR_L
42e0: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  OCK             
42f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4300: 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (15<<8)).#defin
4310: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
4320: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20  LOSE            
4330: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4340: 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (16<<8)).#defin
4350: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
4360: 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  IR_CLOSE        
4370: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4380: 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (17<<8)).#defin
4390: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f  e SQLITE_LOCKED_
43a0: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
43b0: 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20   (SQLITE_LOCKED 
43c0: 7c 20 28 31 3c 3c 38 29 20 29 0a 0a 2f 2a 0a 2a  | (1<<8) )../*.*
43d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
43e0: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
43f0: 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48 31 30 32  Operations {H102
4400: 33 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48 31  30} <H11120> <H1
4410: 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  2700>.**.** Thes
4420: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
4430: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
4440: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
4450: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
4460: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
4470: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
4480: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
4490: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
44a0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f  e xOpen method o
44b0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
44c0: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
44d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44e0: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
44f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
4500: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
4510: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
4520: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4530: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
4540: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
4550: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
4560: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
4570: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4580: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
4590: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
45a0: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
45b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
45c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45d0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
45e0: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
45f0: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
4600: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4610: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
4620: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
4630: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4650: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
4660: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
4670: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4680: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4690: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
46a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
46b0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
46c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46d0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
46e0: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
46f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
4720: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
4730: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4740: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4750: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
4760: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
4770: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4790: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
47a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
47b0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
47c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
47d0: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
47e0: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
47f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4800: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4810: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
4820: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
4830: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
4840: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
4850: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4860: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
4870: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
4880: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
4890: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
48a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
48b0: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
48c0: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
48d0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
48e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
48f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4900: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
4910: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
4920: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
4930: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
4940: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4950: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63  F: Device Charac
4960: 74 65 72 69 73 74 69 63 73 20 7b 48 31 30 32 34  teristics {H1024
4970: 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a  0} <H11120>.**.*
4980: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 61 70  * The xDeviceCap
4990: 61 62 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64  abilities method
49a0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
49b0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
49c0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
49d0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
49e0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
49f0: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
4a00: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
4a10: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
4a20: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
4a30: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
4a40: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
4a50: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
4a60: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
4a70: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
4a80: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
4a90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4aa0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
4ab0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
4ac0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
4ad0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
4ae0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
4af0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
4b00: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
4b10: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
4b20: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
4b30: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
4b40: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
4b50: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
4b60: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
4b70: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
4b80: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
4b90: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
4ba0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
4bb0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
4bc0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
4bd0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
4be0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
4bf0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
4c00: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
4c10: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
4c20: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
4c30: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
4c40: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
4c50: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
4c60: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
4c70: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
4c80: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
4c90: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
4ca0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
4cb0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
4cc0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4cd0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
4ce0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
4cf0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
4d00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
4d10: 31 32 20 20 20 20 20 20 20 30 78 30 30 30 30 30  12       0x00000
4d20: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
4d30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
4d40: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
4d50: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
4d60: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
4d70: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
4d80: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
4d90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
4da0: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
4db0: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  010.#define SQLI
4dc0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
4dd0: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
4de0: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
4df0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
4e00: 36 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  6K       0x00000
4e10: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
4e20: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
4e30: 32 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  2K       0x00000
4e40: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
4e50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
4e60: 34 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  4K       0x00000
4e70: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
4e80: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
4e90: 50 45 4e 44 20 20 20 20 20 30 78 30 30 30 30 30  PEND     0x00000
4ea0: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
4eb0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
4ec0: 49 41 4c 20 20 20 20 20 20 30 78 30 30 30 30 30  IAL      0x00000
4ed0: 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  400../*.** CAPI3
4ee0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
4ef0: 67 20 4c 65 76 65 6c 73 20 7b 48 31 30 32 35 30  g Levels {H10250
4f00: 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48 31 31 33  } <H11120> <H113
4f10: 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  10>.**.** SQLite
4f20: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
4f30: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
4f40: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
4f50: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
4f60: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
4f70: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
4f80: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
4f90: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
4fa0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
4fb0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
4fc0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
4fd0: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
4fe0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4ff0: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
5000: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
5010: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
5020: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
5030: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
5040: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
5050: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5060: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
5070: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5080: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
5090: 20 54 79 70 65 20 46 6c 61 67 73 20 7b 48 31 30   Type Flags {H10
50a0: 32 36 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 2a  260} <H11120>.**
50b0: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
50c0: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
50d0: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
50e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
50f0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
5100: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
5110: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
5120: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
5130: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
5140: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
5150: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
5160: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
5170: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
5180: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
5190: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
51a0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
51b0: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
51c0: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
51d0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
51e0: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
51f0: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
5200: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
5210: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
5220: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
5230: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
5240: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
5250: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
5260: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
5270: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
5280: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
5290: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
52a0: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
52b0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
52c0: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
52d0: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
52e0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
52f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
5300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5310: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
5320: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
5330: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5340: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
5350: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
5360: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
5370: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
5380: 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32 30  le {H11110} <S20
5390: 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  110>.**.** An [s
53a0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
53b0: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
53c0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
53d0: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
53e0: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
53f0: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
5400: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
5410: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
5420: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
5430: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
5440: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
5450: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
5460: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
5470: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
5480: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
5490: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
54a0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
54b0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
54c0: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
54d0: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
54e0: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
54f0: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
5500: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
5510: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
5520: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
5530: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
5540: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
5550: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
5560: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
5570: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
5580: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
5590: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
55a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
55b0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
55c0: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
55d0: 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31  hods Object {H11
55e0: 31 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a  120} <S20110>.**
55f0: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
5600: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
5610: 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e  lite3_vfs] xOpen
5620: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65   method populate
5630: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s an.** [sqlite3
5640: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f  _file] object (o
5650: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79  r, more commonly
5660: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  , a subclass of 
5670: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
5680: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69  file] object) wi
5690: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  th a pointer to 
56a0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
56b0: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54  his object..** T
56c0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
56d0: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75  es the methods u
56e0: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  sed to perform v
56f0: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e  arious operation
5700: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65  s.** against the
5710: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65   open file repre
5720: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73  sented by the [s
5730: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
5740: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ect..**.** If th
5750: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 73  e xOpen method s
5760: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
5770: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
5780: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
5790: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
57a0: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
57b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
57c0: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
57d0: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
57e0: 6e 20 69 66 20 74 68 65 20 78 4f 70 65 6e 20 72  n if the xOpen r
57f0: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20  eported that it 
5800: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  failed.  The.** 
5810: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76  only way to prev
5820: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43  ent a call to xC
5830: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  lose following a
5840: 20 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a 2a 2a   failed xOpen.**
5850: 20 69 73 20 66 6f 72 20 74 68 65 20 78 4f 70 65   is for the xOpe
5860: 6e 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  n to set the sql
5870: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
5880: 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20 4e 55  ds element to NU
5890: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
58a0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
58b0: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
58c0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
58d0: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
58e0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
58f0: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
5900: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
5910: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
5920: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
5930: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
5940: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
5950: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
5960: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
5970: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
5980: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
5990: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
59a0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
59b0: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
59c0: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
59d0: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
59e0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
59f0: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
5a00: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
5a10: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
5a20: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5a30: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
5a40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
5a50: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
5a60: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
5a70: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
5a80: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
5a90: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
5aa0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5ab0: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
5ac0: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
5ad0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
5ae0: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
5af0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
5b00: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
5b10: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
5b20: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
5b30: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
5b40: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
5b50: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
5b60: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
5b70: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
5b80: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
5b90: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
5ba0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
5bb0: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
5bc0: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
5bd0: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
5be0: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
5bf0: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
5c00: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
5c10: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
5c20: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
5c30: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
5c40: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
5c50: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
5c60: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
5c70: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
5c80: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
5c90: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
5ca0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
5cb0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
5cc0: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
5cd0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
5ce0: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
5cf0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
5d00: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
5d10: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
5d20: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
5d30: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
5d40: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
5d50: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
5d60: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
5d70: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
5d80: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
5d90: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
5da0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
5db0: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
5dc0: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
5dd0: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
5de0: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
5df0: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
5e00: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
5e10: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
5e20: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
5e30: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
5e40: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
5e50: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
5e60: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
5e70: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
5e80: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
5e90: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
5ea0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
5eb0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
5ec0: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
5ed0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
5ee0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
5ef0: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
5f00: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
5f10: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
5f20: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
5f30: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
5f40: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
5f50: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
5f60: 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a   conflicts..**.*
5f70: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
5f80: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
5f90: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
5fa0: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
5fb0: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
5fc0: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
5fd0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
5fe0: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
5ff0: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
6000: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
6010: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
6020: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
6030: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
6040: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
6050: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
6060: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
6070: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
6080: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
6090: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
60a0: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
60b0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
60c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
60d0: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
60e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
60f0: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
6100: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6110: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
6120: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6130: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
6140: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6150: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
6160: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6170: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
6180: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6190: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
61a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
61b0: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
61c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
61d0: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
61e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
61f0: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
6200: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6210: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
6220: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
6230: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6240: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6250: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
6260: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
6270: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6280: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6290: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
62a0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
62b0: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
62c0: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
62d0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
62e0: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
62f0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
6300: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
6310: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
6320: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6330: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6340: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6350: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6360: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6370: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
6380: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
6390: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
63a0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
63b0: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
63c0: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
63d0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
63e0: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
63f0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6400: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6410: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
6420: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
6430: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
6440: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6450: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6460: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
6470: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
6480: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
6490: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
64a0: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
64b0: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
64c0: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
64d0: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
64e0: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
64f0: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
6500: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
6510: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
6520: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
6530: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
6540: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
6550: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
6560: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
6570: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
6580: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
6590: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
65a0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
65b0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
65c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
65d0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
65e0: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
65f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
6600: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
6610: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
6620: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
6630: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
6640: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
6650: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6660: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
6670: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
6680: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
6690: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
66a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
66b0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
66c0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
66d0: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
66e0: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
66f0: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
6700: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6710: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
6720: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
6730: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
6740: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
6750: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
6760: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
6770: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
6780: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
6790: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
67a0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
67b0: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
67c0: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
67d0: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
67e0: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
67f0: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
6800: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
6810: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
6820: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
6830: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
6840: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
6850: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
6860: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
6870: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
6880: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
6890: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
68a0: 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30   Opcodes {H11310
68b0: 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a  } <S30800>.**.**
68c0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
68d0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
68e0: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
68f0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
6900: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
6910: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6920: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
6930: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
6940: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
6950: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
6960: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
6970: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
6980: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
6990: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
69a0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
69b0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
69c0: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
69d0: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
69e0: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
69f0: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
6a00: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
6a10: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6a20: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
6a30: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
6a40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
6a50: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
6a60: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6a70: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
6a80: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
6a90: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
6aa0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
6ab0: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
6ac0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
6ad0: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
6ae0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
6af0: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
6b00: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
6b10: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6b20: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
6b30: 41 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65  ATE        1.#de
6b40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
6b50: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
6b60: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
6b70: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
6b80: 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65  YFILE      3.#de
6b90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
6ba0: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
6bb0: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6bc0: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
6bd0: 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30  le {H17110} <S20
6be0: 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  130>.**.** The m
6bf0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
6c00: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
6c10: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
6c20: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
6c30: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
6c40: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
6c50: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
6c60: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
6c70: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
6c80: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
6c90: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
6ca0: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
6cb0: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
6cc0: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
6cd0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
6ce0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
6cf0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
6d00: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
6d10: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
6d20: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
6d30: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
6d40: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
6d50: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6d60: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
6d70: 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31  t {H11140} <S201
6d80: 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  00>.**.** An ins
6d90: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
6da0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
6db0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
6dc0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
6dd0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
6de0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
6df0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
6e00: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
6e10: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
6e20: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
6e30: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
6e40: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
6e50: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
6e60: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
6e70: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
6e80: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
6e90: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
6ea0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
6eb0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
6ec0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
6ed0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
6ee0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
6ef0: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
6f00: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
6f10: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
6f20: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
6f30: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
6f40: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
6f50: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
6f60: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
6f70: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
6f80: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
6f90: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
6fa0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
6fb0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
6fc0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
6fd0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
6fe0: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
6ff0: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7000: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7010: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7020: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
7030: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
7040: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
7050: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
7060: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
7070: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
7080: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
7090: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
70a0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
70b0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
70c0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
70d0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
70e0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
70f0: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
7100: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
7110: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
7120: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
7130: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
7140: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
7150: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
7160: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
7170: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
7180: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
7190: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
71a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
71b0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
71c0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
71d0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
71e0: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
71f0: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
7200: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
7210: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
7220: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
7230: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
7240: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
7250: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
7260: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
7270: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
7280: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
7290: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
72a0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
72b0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
72c0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
72d0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
72e0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
72f0: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
7300: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
7310: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
7320: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
7330: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
7340: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
7350: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
7360: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
7370: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
7380: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
7390: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
73a0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
73b0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
73c0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
73d0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
73e0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
73f0: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
7400: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
7410: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
7420: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
7430: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
7440: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
7450: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
7460: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
7470: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
7480: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
7490: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
74a0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
74b0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
74c0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
74d0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
74e0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
74f0: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
7500: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
7510: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
7520: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
7530: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
7540: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
7550: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
7560: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
7570: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
7580: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
7590: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
75a0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
75b0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
75c0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
75d0: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
75e0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
75f0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
7600: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
7610: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
7620: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
7630: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
7640: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
7650: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
7660: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
7670: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
7680: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
7690: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
76a0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
76b0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
76c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
76d0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
76e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
76f0: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
7700: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
7710: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
7720: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
7730: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
7740: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
7750: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
7760: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
7770: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
7780: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
7790: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
77a0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
77b0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
77c0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
77d0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
77e0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
77f0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
7800: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7810: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
7820: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
7830: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
7840: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
7850: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
7860: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7870: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
7880: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
7890: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
78a0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
78b0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
78c0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
78d0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
78e0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
78f0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
7900: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
7910: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
7920: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
7930: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
7940: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
7950: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
7960: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
7970: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
7980: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
7990: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
79a0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
79b0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
79c0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
79d0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
79e0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
79f0: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
7a00: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
7a10: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
7a20: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
7a30: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
7a40: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
7a50: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
7a60: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
7a70: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
7a80: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
7a90: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
7aa0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
7ab0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
7ac0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
7ad0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
7ae0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
7af0: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
7b00: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
7b10: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
7b20: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
7b30: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
7b40: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
7b50: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
7b60: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
7b70: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
7b80: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
7b90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
7ba0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
7bb0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7bc0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7bd0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
7be0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
7bf0: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
7c00: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
7c10: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
7c20: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
7c30: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
7c40: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
7c50: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
7c60: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
7c70: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
7c80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
7c90: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
7ca0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
7cb0: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
7cc0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
7cd0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
7ce0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
7cf0: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
7d00: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
7d10: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
7d20: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
7d30: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
7d40: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
7d50: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
7d60: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
7d70: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
7d80: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
7d90: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
7da0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
7db0: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
7dc0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
7dd0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
7de0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
7df0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
7e00: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
7e10: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
7e20: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
7e30: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
7e40: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
7e50: 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74  ..**.** At least
7e60: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
7e70: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
7e80: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
7e90: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
7ea0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
7eb0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
7ec0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
7ed0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
7ee0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
7ef0: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
7f00: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
7f10: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
7f20: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
7f30: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
7f40: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
7f50: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
7f60: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
7f70: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7f80: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
7f90: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
7fa0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7fb0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
7fc0: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
7fd0: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
7fe0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
7ff0: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
8000: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
8010: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
8020: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
8030: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
8040: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
8050: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
8060: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
8070: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
8080: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  l..**.** The fla
8090: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
80a0: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
80b0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
80c0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
80d0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
80e0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
80f0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
8100: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
8110: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
8120: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
8130: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
8140: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8150: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
8160: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
8170: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
8180: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
8190: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
81a0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
81b0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
81c0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
81d0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
81e0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
81f0: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
8200: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
8210: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
8220: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
8230: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
8240: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
8250: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
8260: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
8270: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8280: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8290: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
82a0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
82b0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
82c0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
82d0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
82e0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
82f0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8300: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8310: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
8320: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
8330: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
8340: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
8350: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
8360: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
8370: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
8380: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
8390: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
83a0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
83b0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
83c0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
83d0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
83e0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
83f0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
8400: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
8410: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
8420: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
8430: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
8440: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
8450: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
8460: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
8470: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
8480: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
8490: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
84a0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
84b0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
84c0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
84d0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
84e0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
84f0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
8500: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
8510: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
8520: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
8530: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
8540: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
8550: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
8560: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
8570: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
8580: 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ..**.*/.typedef 
8590: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
85a0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
85b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
85c0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
85d0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
85e0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
85f0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  sion number */. 
8600: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
8610: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
8620: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
8630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
8640: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
8650: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
8660: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
8670: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
8680: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
8690: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
86a0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
86b0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
86c0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
86d0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
86e0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
86f0: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
8700: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
8710: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
8720: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
8730: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
8740: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
8750: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
8760: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
8770: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
8780: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
8790: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
87a0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
87b0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
87c0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
87d0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
87e0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
87f0: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
8800: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
8810: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
8820: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
8830: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
8840: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
8850: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
8860: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
8870: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
8880: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
8890: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
88a0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
88b0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
88c0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
88d0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
88e0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
88f0: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
8900: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
8910: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
8920: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
8930: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
8940: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
8950: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
8960: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
8970: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
8980: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
8990: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
89a0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
89b0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
89c0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
89d0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
89e0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
89f0: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
8a00: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
8a10: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
8a20: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
8a30: 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   /* New fields m
8a40: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
8a50: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
8a60: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
8a70: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
8a80: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
8a90: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
8aa0: 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  . */.};../*.** C
8ab0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
8ac0: 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
8ad0: 46 53 20 6d 65 74 68 6f 64 20 7b 48 31 31 31 39  FS method {H1119
8ae0: 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a  0} <H11140>.**.*
8af0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
8b00: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
8b10: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
8b20: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
8b30: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
8b40: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
8b50: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
8b60: 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65  . {END}  They de
8b70: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
8b80: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
8b90: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
8ba0: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
8bb0: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
8bc0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
8bd0: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
8be0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
8bf0: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
8c00: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
8c10: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
8c20: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
8c30: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
8c40: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
8c50: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
8c60: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
8c70: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a  e and writable..
8c80: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
8c90: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
8ca0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
8cb0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
8cc0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
8cd0: 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  dable..*/.#defin
8ce0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
8cf0: 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
8d00: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
8d10: 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64  S_READWRITE 1.#d
8d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
8d30: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a  ESS_READ      2.
8d40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
8d50: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
8d60: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b  SQLite Library {
8d70: 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30 3e  H10130} <S20000>
8d80: 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30100>.**.** T
8d90: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
8da0: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
8db0: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
8dc0: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
8dd0: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
8de0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
8df0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
8e00: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
8e10: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
8e20: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
8e30: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
8e40: 54 68 69 73 20 72 6f 75 74 69 6e 65 73 20 61 72  This routines ar
8e50: 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
8e60: 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
8e70: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
8e80: 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
8e90: 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
8ea0: 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
8eb0: 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
8ec0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
8ed0: 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
8ee0: 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
8ef0: 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
8f00: 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
8f10: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
8f20: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
8f30: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
8f40: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
8f50: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
8f60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
8f70: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
8f80: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
8f90: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
8fa0: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
8fb0: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
8fc0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8fd0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
8fe0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
8ff0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
9000: 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e  down().  Only an
9010: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
9020: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
9030: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
9040: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
9050: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
9060: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
9070: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a  less no-ops..**.
9080: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
9090: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
90a0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
90b0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
90c0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
90d0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
90e0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
90f0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
9100: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 4f 6e  nitialize().  On
9110: 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69  ly.** an effecti
9120: 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ve call to sqlit
9130: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f  e3_shutdown() do
9140: 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c  es any deinitial
9150: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20  ization..** All 
9160: 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c  other valid call
9170: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  s to sqlite3_shu
9180: 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d  tdown() are harm
9190: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a  less no-ops..**.
91a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
91b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65  nitialize() inte
91c0: 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73  rface is threads
91d0: 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33  afe, but sqlite3
91e0: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69  _shutdown().** i
91f0: 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69  s not.  The sqli
9200: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
9210: 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e  nterface must on
9220: 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  ly be called fro
9230: 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68  m a.** single th
9240: 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20  read.  All open 
9250: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
9260: 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63  tions] must be c
9270: 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a  losed and all.**
9280: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65   other SQLite re
9290: 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20  sources must be 
92a0: 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f  deallocated prio
92b0: 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a  r to invoking.**
92c0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
92d0: 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67  n()..**.** Among
92e0: 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73   other things, s
92f0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9300: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
9310: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
9320: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
9330: 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  , sqlite3_shutdo
9340: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
9350: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
9360: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nd()..**.** The 
9370: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9380: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
9390: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
93a0: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
93b0: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
93c0: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
93d0: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
93e0: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
93f0: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
9400: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
9410: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
9420: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
9430: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
9440: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
9450: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
9460: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
9470: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
9480: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
9490: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
94a0: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
94b0: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
94c0: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
94d0: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
94e0: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
94f0: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
9500: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
9510: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
9520: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
9530: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
9540: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
9550: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
9560: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9570: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
9580: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
9590: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
95a0: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
95b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
95c0: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
95d0: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
95e0: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
95f0: 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66  dy.  However, if
9600: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
9610: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
9620: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
9630: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
9640: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
9650: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
9660: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
9670: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
9680: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
9690: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
96a0: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
96b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
96c0: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
96d0: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
96e0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
96f0: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
9700: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
9710: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
9720: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
9730: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
9740: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
9750: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
9760: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
9770: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
9780: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
9790: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
97a0: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
97b0: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
97c0: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
97d0: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
97e0: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
97f0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
9800: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
9810: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
9820: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
9830: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
9840: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
9850: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
9860: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
9870: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
9880: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
9890: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
98a0: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
98b0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
98c0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
98d0: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
98e0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
98f0: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
9900: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
9910: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
9920: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
9930: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
9940: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
9950: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
9960: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
9970: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
9980: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
9990: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
99a0: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
99b0: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
99c0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
99d0: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
99e0: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
99f0: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
9a00: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
9a10: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
9a20: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
9a30: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
9a40: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
9a50: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
9a60: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
9a70: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
9a80: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
9a90: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
9aa0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
9ab0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
9ac0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9ad0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
9ae0: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
9af0: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
9b00: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
9b10: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9b20: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
9b30: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
9b40: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
9b50: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
9b60: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
9b70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
9b80: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
9b90: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
9ba0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
9bb0: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
9bc0: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
9bd0: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
9be0: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
9bf0: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
9c00: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
9c10: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
9c20: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
9c30: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
9c40: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
9c50: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
9c60: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
9c70: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
9c80: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
9c90: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
9ca0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
9cb0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
9cc0: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
9cd0: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
9ce0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
9cf0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
9d00: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
9d10: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
9d20: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
9d30: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
9d40: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
9d50: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
9d60: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
9d70: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
9d80: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e  ialize(void);.in
9d90: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
9da0: 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  wn(void);.int sq
9db0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
9dc0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
9dd0: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
9de0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9df0: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
9e00: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b  SQLite Library {
9e10: 48 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30 3e  H14100} <S20000>
9e20: 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45  <S30200>.** EXPE
9e30: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
9e40: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
9e50: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
9e60: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
9e70: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
9e80: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
9e90: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
9ea0: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
9eb0: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
9ec0: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
9ed0: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
9ee0: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
9ef0: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
9f00: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
9f10: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
9f20: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
9f30: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
9f40: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
9f50: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
9f60: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
9f70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
9f80: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
9f90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
9fa0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
9fb0: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
9fc0: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
9fd0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
9fe0: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
9ff0: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
a000: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
a010: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
a020: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
a030: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a040: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
a050: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
a060: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
a070: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
a080: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
a090: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
a0a0: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
a0b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a0c0: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
a0d0: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
a0e0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
a0f0: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
a100: 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  that sqlite3_con
a110: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
a120: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
a130: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
a140: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
a150: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
a160: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a170: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
a180: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
a190: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a1a0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
a1b0: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
a1c0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20  _SINGLETHREAD | 
a1d0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
a1e0: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
a1f0: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
a200: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
a210: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
a220: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
a230: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
a240: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
a250: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
a260: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
a270: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
a280: 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
a290: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
a2a0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20  t..**.** When a 
a2b0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
a2c0: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
a2d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
a2e0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
a2f0: 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74  ]..** If the opt
a300: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
a310: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
a320: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
a330: 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
a340: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
a350: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
a360: 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
a370: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
a380: 2a 20 5b 48 31 34 31 30 33 5d 20 5b 48 31 34 31  * [H14103] [H141
a390: 30 36 5d 20 5b 48 31 34 31 32 30 5d 20 5b 48 31  06] [H14120] [H1
a3a0: 34 31 32 33 5d 20 5b 48 31 34 31 32 36 5d 20 5b  4123] [H14126] [
a3b0: 48 31 34 31 32 39 5d 20 5b 48 31 34 31 33 32 5d  H14129] [H14132]
a3c0: 20 5b 48 31 34 31 33 35 5d 0a 2a 2a 20 5b 48 31   [H14135].** [H1
a3d0: 34 31 33 38 5d 20 5b 48 31 34 31 34 31 5d 20 5b  4138] [H14141] [
a3e0: 48 31 34 31 34 34 5d 20 5b 48 31 34 31 34 37 5d  H14144] [H14147]
a3f0: 20 5b 48 31 34 31 35 30 5d 20 5b 48 31 34 31 35   [H14150] [H1415
a400: 33 5d 20 5b 48 31 34 31 35 36 5d 20 5b 48 31 34  3] [H14156] [H14
a410: 31 35 39 5d 0a 2a 2a 20 5b 48 31 34 31 36 32 5d  159].** [H14162]
a420: 20 5b 48 31 34 31 36 35 5d 20 5b 48 31 34 31 36   [H14165] [H1416
a430: 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  8].*/.SQLITE_EXP
a440: 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71  ERIMENTAL int sq
a450: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
a460: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
a470: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
a480: 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
a490: 65 63 74 69 6f 6e 73 20 20 7b 48 31 34 32 30 30  ections  {H14200
a4a0: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58  } <S20000>.** EX
a4b0: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
a4c0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
a4d0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
a4e0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
a4f0: 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
a500: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
a510: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
a520: 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
a530: 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
a540: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
a550: 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
a560: 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
a570: 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
a580: 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
a590: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
a5a0: 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
a5b0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
a5c0: 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
a5d0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
a5e0: 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20  erface can only 
a5f0: 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61 74  be used immediat
a600: 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 65  ely after.** the
a610: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
a620: 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 20  tion is created 
a630: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  using [sqlite3_o
a640: 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  pen()],.** [sqli
a650: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
a660: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
a670: 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  v2()].  .**.** T
a680: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
a690: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
a6a0: 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
a6b0: 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66    is the.** conf
a6c0: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20 2d  iguration verb -
a6d0: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
a6e0: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
a6f0: 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f  what.** aspect o
a700: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
a710: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
a720: 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
a730: 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f  .** The only cho
a740: 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61 6c  ice for this val
a750: 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42  ue is [SQLITE_DB
a760: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
a770: 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20  ]..** New verbs 
a780: 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65  are likely to be
a790: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
a7a0: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
a7b0: 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  ite..** Addition
a7c0: 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65 70  al arguments dep
a7d0: 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62 2e  end on the verb.
a7e0: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
a7f0: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 32 30 33 5d  nts:.** [H14203]
a800: 20 5b 48 31 34 32 30 36 5d 20 5b 48 31 34 32 30   [H14206] [H1420
a810: 39 5d 20 5b 48 31 34 32 31 32 5d 20 5b 48 31 34  9] [H14212] [H14
a820: 32 31 35 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  215].*/.SQLITE_E
a830: 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
a840: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
a850: 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
a860: 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
a870: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
a880: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
a890: 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 3c  tines {H10155} <
a8a0: 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 45 52  S20120>.** EXPER
a8b0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e  IMENTAL.**.** An
a8c0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
a8d0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
a8e0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
a8f0: 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
a900: 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
a910: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
a920: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
a930: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
a940: 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
a950: 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
a960: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
a970: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
a980: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
a990: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
a9a0: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
a9b0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
a9c0: 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
a9d0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
a9e0: 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
a9f0: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f  CONFIG_MALLOC] o
aa00: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
aa10: 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a  _GETMALLOC].  .*
aa20: 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e  * By creating an
aa30: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
aa40: 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
aa50: 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
aa60: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
aa70: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
aa80: 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67  LLOC]).** during
aa90: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
aaa0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  an application c
aab0: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
aac0: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
aad0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
aae0: 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c  ubsystem for SQL
aaf0: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
ab00: 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e  ll of its.** dyn
ab10: 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64  amic memory need
ab20: 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
ab30: 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20  at SQLite comes 
ab40: 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75  with several [bu
ab50: 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
ab60: 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61  locators].** tha
ab70: 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20  t are perfectly 
ab80: 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65  adequate for the
ab90: 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61   overwhelming ma
aba0: 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  jority of applic
abb0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68  ations.** and th
abc0: 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  at this object i
abd0: 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f  s only useful to
abe0: 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79   a tiny minority
abf0: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
ac00: 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c  .** with special
ac10: 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ized memory allo
ac20: 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65  cation requireme
ac30: 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  nts.  This objec
ac40: 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65  t is.** also use
ac50: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
ac60: 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   of SQLite in or
ac70: 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  der to specify a
ac80: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
ac90: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
aca0: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73  r that simulates
acb0: 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d   memory out-of-m
acc0: 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73  emory conditions
acd0: 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20   in.** order to 
ace0: 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
acf0: 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63  te recovers grac
ad00: 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68  efully from such
ad10: 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a  .** conditions..
ad20: 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f  **.** The xMallo
ad30: 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68  c and xFree meth
ad40: 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
ad50: 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
ad60: 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
ad70: 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
ad80: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
ad90: 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61  ary..** The xRea
ada0: 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 74  lloc method must
adb0: 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c   work like reall
adc0: 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73 74  oc() from the st
add0: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
ade0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78 63  .** with the exc
adf0: 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20 74  eption that if t
ae00: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
ae10: 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69  nt to xRealloc i
ae20: 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c  s zero,.** xReal
ae30: 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e 6f  loc must be a no
ae40: 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f  -op - it must no
ae50: 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c  t perform any al
ae60: 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64  location or.** d
ae70: 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 53 51  eallocation.  SQ
ae80: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 64 73  Lite guaranteeds
ae90: 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
aea0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
aeb0: 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61  xRealloc is alwa
aec0: 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72  ys a value retur
aed0: 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63  ned by a prior c
aee0: 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e  all to xRoundup.
aef0: 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 61  .** And so in ca
af00: 73 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e 64  ses where xRound
af10: 75 70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  up always return
af20: 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d  s a positive num
af30: 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  ber,.** xRealloc
af40: 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 61   can perform exa
af50: 63 74 6c 79 20 61 73 20 74 68 65 20 73 74 61 6e  ctly as the stan
af60: 64 61 72 64 20 6c 69 62 72 61 72 79 20 72 65 61  dard library rea
af70: 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74  lloc() and.** st
af80: 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69  ill be in compli
af90: 61 6e 63 65 20 77 69 74 68 20 74 68 69 73 20 73  ance with this s
afa0: 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a  pecification..**
afb0: 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64  .** xSize should
afc0: 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f   return the allo
afd0: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20  cated size of a 
afe0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
aff0: 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  n.** previously 
b000: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d  obtained from xM
b010: 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f  alloc or xReallo
b020: 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65  c.  The allocate
b030: 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77  d size.** is alw
b040: 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20  ays at least as 
b050: 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65  big as the reque
b060: 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61  sted size but ma
b070: 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a  y be larger..**.
b080: 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20  ** The xRoundup 
b090: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77  method returns w
b0a0: 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65  hat would be the
b0b0: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
b0c0: 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  of.** a memory a
b0d0: 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20  llocation given 
b0e0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71  a particular req
b0f0: 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f  uested size.  Mo
b100: 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  st memory.** all
b110: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
b120: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
b130: 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20  ons at least to 
b140: 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c  the next multipl
b150: 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65  e.** of 8.  Some
b160: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
b170: 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72  d up to a larger
b180: 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20   multiple or to 
b190: 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a  a power of 2..**
b1a0: 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   Every memory al
b1b0: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
b1c0: 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75   coming in throu
b1d0: 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  gh [sqlite3_mall
b1e0: 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  oc()].** or [sql
b1f0: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
b200: 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75  first calls xRou
b210: 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64  ndup.  If xRound
b220: 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a  up returns 0, .*
b230: 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68  * that causes th
b240: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
b250: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b260: 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  n to fail..**.**
b270: 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   The xInit metho
b280: 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  d initializes th
b290: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
b2a0: 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c  or.  (For exampl
b2b0: 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
b2c0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
b2d0: 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
b2e0: 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
b2f0: 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
b300: 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
b310: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
b320: 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
b330: 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
b340: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
b350: 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
b360: 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
b370: 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
b380: 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
b390: 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
b3a0: 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
b3b0: 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
b3c0: 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
b3d0: 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
b3e0: 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
b3f0: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
b400: 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
b410: 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
b420: 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
b430: 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
b440: 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
b450: 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
b460: 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
b470: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
b480: 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
b490: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
b4a0: 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
b4b0: 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
b4c0: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
b4d0: 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
b4e0: 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
b4f0: 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
b500: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
b510: 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
b520: 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
b530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
b540: 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
b550: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
b560: 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
b570: 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
b580: 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
b590: 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
b5a0: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
b5b0: 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
b5c0: 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
b5d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
b5e0: 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
b5f0: 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
b600: 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
b610: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
b620: 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
b630: 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
b640: 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
b650: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
b660: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
b670: 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
b680: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
b690: 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
b6a0: 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
b6b0: 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
b6c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
b6d0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
b6e0: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
b6f0: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
b700: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
b710: 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
b720: 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
b730: 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
b740: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
b750: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
b760: 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
b770: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
b780: 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
b790: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
b7a0: 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
b7b0: 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
b7c0: 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
b7d0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
b7e0: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
b7f0: 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
b800: 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
b810: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
b820: 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
b830: 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
b840: 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
b850: 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
b860: 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
b870: 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
b880: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
b890: 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
b8a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
b8b0: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
b8c0: 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
b8d0: 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
b8e0: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
b8f0: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
b900: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
b910: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
b920: 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
b930: 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
b940: 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
b950: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
b960: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
b970: 20 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 30 30   {H10160} <S2000
b980: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
b990: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  AL.**.** These c
b9a0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
b9b0: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
b9c0: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
b9d0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
b9e0: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
b9f0: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
ba00: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
ba10: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
ba20: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
ba30: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
ba40: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
ba50: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
ba60: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
ba70: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
ba80: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
ba90: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
baa0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
bab0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
bac0: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
bad0: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
bae0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
baf0: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
bb00: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
bb10: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
bb20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
bb30: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
bb40: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
bb50: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
bb60: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
bb70: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
bb80: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
bb90: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
bba0: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
bbb0: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
bbc0: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
bbd0: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
bbe0: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
bbf0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
bc00: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
bc10: 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a  tion disables.**
bc20: 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
bc30: 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
bc40: 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
bc50: 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
bc60: 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
bc70: 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a  le thread.</dd>.
bc80: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
bc90: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
bca0: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
bcb0: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
bcc0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
bcd0: 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74  ption.  This opt
bce0: 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20  ion disables.** 
bcf0: 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
bd00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bd10: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
bd20: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
bd30: 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
bd40: 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
bd50: 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
bd60: 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
bd70: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
bd80: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
bd90: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
bda0: 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
bdb0: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
bdc0: 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
bdd0: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
bde0: 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
bdf0: 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
be00: 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
be10: 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
be20: 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
be30: 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
be40: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
be50: 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
be60: 61 6d 65 20 74 69 6d 65 2e 20 20 53 65 65 20 74  ame time.  See t
be70: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
be80: 64 65 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 61  de].** documenta
be90: 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
bea0: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
beb0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bec0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
bed0: 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
bee0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
bef0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
bf00: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
bf10: 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
bf20: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
bf30: 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
bf40: 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
bf50: 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
bf60: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
bf70: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
bf80: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
bf90: 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
bfa0: 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
bfb0: 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
bfc0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
bfd0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
bfe0: 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
bff0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
c000: 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
c010: 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
c020: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c030: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
c040: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
c050: 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
c060: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
c070: 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
c080: 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
c090: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
c0a0: 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
c0b0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
c0c0: 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
c0d0: 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
c0e0: 74 69 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68 65  time..** See the
c0f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
c100: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
c110: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
c120: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e  nformation.</dd>
c130: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c140: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
c150: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
c160: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
c170: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
c180: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
c190: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
c1a0: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
c1b0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
c1c0: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
c1d0: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
c1e0: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
c1f0: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
c200: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c210: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
c220: 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
c230: 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
c240: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
c250: 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
c260: 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ite.</dd>.**.** 
c270: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
c280: 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
c290: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c2a0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
c2b0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
c2c0: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
c2d0: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
c2e0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
c2f0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
c300: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
c310: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
c320: 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
c330: 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
c340: 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
c350: 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
c360: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
c370: 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ..** This option
c380: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
c390: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
c3a0: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
c3b0: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
c3c0: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
c3d0: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
c3e0: 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
c3f0: 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
c400: 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
c410: 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
c420: 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ple.</dd>.**.** 
c430: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
c440: 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
c450: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c460: 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
c470: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
c480: 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
c490: 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c  ed as a .** bool
c4a0: 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
c4b0: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
c4c0: 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
c4d0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c4e0: 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63  on .** statistic
c4f0: 73 2e 20 57 68 65 6e 20 64 69 73 61 62 6c 65 64  s. When disabled
c500: 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
c510: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
c520: 73 20 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e  s become .** non
c530: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
c540: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
c550: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
c560: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
c570: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
c580: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
c590: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
c5a0: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
c5b0: 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  mit()].**   <li>
c5c0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
c5d0: 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a  ()].**   </ul>.*
c5e0: 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
c5f0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c600: 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
c610: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
c620: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
c630: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
c640: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
c650: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
c660: 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
c670: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
c680: 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
c690: 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
c6a0: 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
c6b0: 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
c6c0: 20 74 68 65 20 73 63 72 61 63 68 20 61 6c 6c 6f   the scrach allo
c6d0: 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
c6e0: 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
c6f0: 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
c700: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
c710: 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
c720: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
c730: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
c740: 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
c750: 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
c760: 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
c770: 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70   of 16. The sz p
c780: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
c790: 62 65 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a  be a few bytes.*
c7a0: 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  * larger than th
c7b0: 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 63 68  e actual scratch
c7c0: 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20   space required 
c7d0: 64 75 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20  due to internal 
c7e0: 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65  overhead..** The
c7f0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
c800: 73 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72 20 74  should pointer t
c810: 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  o an 8-byte alig
c820: 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66  ned buffer.** of
c830: 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
c840: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
c850: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  ** SQLite will u
c860: 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
c870: 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
c880: 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74  er at once per t
c890: 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73  hread, so.** N s
c8a0: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
c8b0: 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
c8c0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
c8d0: 68 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a  hreads.  The sz.
c8e0: 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  ** parameter sho
c8f0: 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 74  uld be 6 times t
c900: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
c910: 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
c920: 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63  page size..** Sc
c930: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 61 72  ratch buffers ar
c940: 65 20 75 73 65 64 20 61 73 20 70 61 72 74 20 6f  e used as part o
c950: 66 20 74 68 65 20 62 74 72 65 65 20 62 61 6c 61  f the btree bala
c960: 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  nce operation.  
c970: 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20  If.** The btree 
c980: 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61  balancer needs a
c990: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79  dditional memory
c9a0: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
c9b0: 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73  provided by.** s
c9c0: 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 6f  cratch buffers o
c9d0: 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20  r if no scratch 
c9e0: 62 75 66 66 65 72 20 73 70 61 63 65 20 69 73 20  buffer space is 
c9f0: 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
ca00: 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74  SQLite.** goes t
ca10: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
ca20: 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74  c()] to obtain t
ca30: 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65  he memory it nee
ca40: 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ds.</dd>.**.** <
ca50: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
ca60: 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
ca70: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
ca80: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
ca90: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
caa0: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
cab0: 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
cac0: 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
cad0: 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
cae0: 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63  default page cac
caf0: 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e  he implemenation
cb00: 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
cb10: 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
cb20: 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
cb30: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
cb40: 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
cb50: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
cb60: 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
cb70: 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
cb80: 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69  NFIG_PCACHE opti
cb90: 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
cba0: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
cbb0: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
cbc0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
cbd0: 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
cbe0: 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
cbf0: 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
cc00: 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
cc10: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
cc20: 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
cc30: 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
cc40: 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
cc50: 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
cc60: 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
cc70: 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
cc80: 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
cc90: 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
cca0: 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
ccb0: 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
ccc0: 2e 20 20 54 68 65 20 70 61 67 65 20 68 65 61 64  .  The page head
ccd0: 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
cce0: 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
ccf0: 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
cd00: 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
cd10: 20 20 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73    It is harmless
cd20: 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
cd30: 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
cd40: 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20  ** to make sz a 
cd50: 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65  little too large
cd60: 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
cd70: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
cd80: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f  point to an allo
cd90: 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61  cation of at lea
cda0: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
cdb0: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69   memory..** SQLi
cdc0: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
cdd0: 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
cde0: 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
cdf0: 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
ce00: 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
ce10: 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
ce20: 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
ce30: 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
ce40: 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c  .  If additional
ce50: 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
ce60: 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
ce70: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
ce80: 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
ce90: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
cea0: 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
ceb0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
cec0: 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
ced0: 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
cee0: 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65  ce..** The imple
cef0: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
cf00: 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  use one or more 
cf10: 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 72 73  of the N buffers
cf20: 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d   to hold .** mem
cf30: 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69  ory accounting i
cf40: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65 20  nformation. The 
cf50: 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
cf60: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
cf70: 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
cf80: 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
cf90: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
cfa0: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
cfb0: 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
cfc0: 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
cfd0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
cfe0: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
cff0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
d000: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
d010: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
d020: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
d030: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
d040: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
d050: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
d060: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
d070: 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
d080: 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
d090: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
d0a0: 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
d0b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
d0c0: 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
d0d0: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
d0e0: 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61  nts: An 8-byte a
d0f0: 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
d100: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
d110: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
d120: 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
d130: 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
d140: 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
d150: 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 49  ation size..** I
d160: 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
d170: 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
d180: 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
d190: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
d1a0: 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
d1b0: 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
d1c0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
d1d0: 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
d1e0: 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
d1f0: 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
d200: 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
d210: 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
d220: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
d230: 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72   If the.** memor
d240: 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
d250: 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72   NULL and either
d260: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
d270: 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b  MEMSYS3] or.** [
d280: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
d290: 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e  MSYS5] are defin
d2a0: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ed, then the alt
d2b0: 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
d2c0: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
d2d0: 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
d2e0: 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
d2f0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d300: 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
d310: 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
d320: 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
d330: 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
d340: 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
d350: 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
d360: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
d370: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
d380: 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
d390: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d3a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
d3b0: 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
d3c0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
d3d0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
d3e0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
d3f0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
d400: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
d410: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
d420: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
d430: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
d440: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
d450: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
d460: 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
d470: 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
d480: 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75   place.** the mu
d490: 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
d4a0: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c  lt into SQLite.<
d4b0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
d4c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
d4d0: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
d4e0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
d4f0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
d500: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
d510: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
d520: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
d530: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
d540: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
d550: 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
d560: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
d570: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
d580: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
d590: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
d5a0: 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
d5b0: 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f  tines..** This o
d5c0: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
d5d0: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
d5e0: 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
d5f0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
d600: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
d610: 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
d620: 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
d630: 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
d640: 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
d650: 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
d660: 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  mple.</dd>.**.**
d670: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
d680: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
d690: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
d6a0: 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
d6b0: 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
d6c0: 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61  termine the defa
d6d0: 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ult.** memory al
d6e0: 6c 6f 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69  location lookasi
d6f0: 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e  de optimization.
d700: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
d710: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
d720: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
d730: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
d740: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
d750: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
d760: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
d770: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
d780: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d790: 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  .  This option s
d7a0: 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65  ets the.** <i>de
d7b0: 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
d7c0: 69 64 65 20 73 69 7a 65 2e 20 20 54 68 65 20 5b  ide size.  The [
d7d0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
d7e0: 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65  LOOKASIDE].** ve
d7f0: 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  rb to [sqlite3_d
d800: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
d810: 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
d820: 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
d830: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
d840: 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
d850: 6f 6e 6e 65 63 74 69 6f 6e 73 2e 3c 2f 64 64 3e  onnections.</dd>
d860: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
d870: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c  E_CONFIG_PCACHE<
d880: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
d890: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
d8a0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
d8b0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
d8c0: 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c  er to.** an [sql
d8d0: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
d8e0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ods] object.  Th
d8f0: 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
d900: 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ies the interfac
d910: 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d  e.** to a custom
d920: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
d930: 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53 51 4c  ementation.  SQL
d940: 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
d950: 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63   of the.** objec
d960: 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f  t and uses it fo
d970: 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
d980: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
d990: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d9a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
d9b0: 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  TPCACHE</dt>.** 
d9c0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
d9d0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
d9e0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
d9f0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
da00: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
da10: 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
da20: 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
da30: 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65  ies of the curre
da40: 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  nt.** page cache
da50: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
da60: 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
da70: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64  .</dd>.**.** </d
da80: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
da90: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
daa0: 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
dab0: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
dac0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
dad0: 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
dae0: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
daf0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
db00: 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
db10: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
db20: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
db30: 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
db40: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
db50: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
db60: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
db70: 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
db80: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
db90: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
dba0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
dbb0: 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
dbc0: 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
dbd0: 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
dbe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
dbf0: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
dc00: 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
dc10: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
dc20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dc30: 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
dc40: 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
dc50: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
dc60: 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
dc70: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
dc80: 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
dc90: 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
dca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
dcb0: 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
dcc0: 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
dcd0: 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
dce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dcf0: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
dd00: 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
dd10: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
dd20: 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
dd30: 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
dd40: 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
dd50: 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
dd60: 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
dd70: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
dd80: 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
dd90: 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
dda0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
ddb0: 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
ddc0: 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  14  /* sqlite3_p
ddd0: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
dde0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ddf0: 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
de00: 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69  E    15  /* sqli
de10: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
de20: 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ds* */../*.** CA
de30: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
de40: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48  ation Options {H
de50: 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30 3e 0a  10170} <S20000>.
de60: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
de70: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
de80: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
de90: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
dea0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
deb0: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
dec0: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
ded0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
dee0: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
def0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
df00: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
df10: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
df20: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
df30: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
df40: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
df50: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
df60: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
df70: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
df80: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
df90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
dfa0: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
dfb0: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
dfc0: 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
dfd0: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
dfe0: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
dff0: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
e000: 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
e010: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
e020: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
e030: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
e040: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
e050: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
e060: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
e070: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
e080: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
e090: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
e0a0: 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
e0b0: 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
e0c0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
e0d0: 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
e0e0: 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
e0f0: 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
e100: 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
e110: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
e120: 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
e130: 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
e140: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e150: 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  on]..** The firs
e160: 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
e170: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
e180: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
e190: 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
e1a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d   pointer to an m
e1b0: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
e1c0: 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
e1d0: 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 54 68 65  e memory..** The
e1e0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
e1f0: 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
e200: 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
e210: 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
e220: 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
e230: 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
e240: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
e250: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 65 63  loc()].  The sec
e260: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
e270: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
e280: 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
e290: 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
e2a0: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
e2b0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
e2c0: 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
e2d0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
e2e0: 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
e2f0: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
e300: 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
e310: 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
e320: 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
e330: 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
e340: 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
e350: 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
e360: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
e370: 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
e380: 79 2e 20 20 49 66 20 74 68 65 20 73 65 63 6f 6e  y.  If the secon
e390: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 6f  d argument is no
e3a0: 74 0a 2a 2a 20 61 20 6d 75 6c 74 69 70 6c 65 20  t.** a multiple 
e3b0: 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
e3c0: 72 6e 61 6c 6c 79 20 72 6f 75 6e 64 65 64 20 64  rnally rounded d
e3d0: 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
e3e0: 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d 75 6c 74 69  smaller.** multi
e3f0: 70 6c 65 20 6f 66 20 38 2e 20 20 53 65 65 20 61  ple of 8.  See a
e400: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  lso: [SQLITE_CON
e410: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 3c 2f  FIG_LOOKASIDE]</
e420: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
e430: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e440: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
e450: 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a  SIDE    1001  /*
e460: 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
e470: 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
e480: 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
e490: 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
e4a0: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32  esult Codes {H12
e4b0: 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  200} <S10700>.**
e4c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e4d0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
e4e0: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
e4f0: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
e500: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
e510: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
e520: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
e530: 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64  Lite. The extend
e540: 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
e550: 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
e560: 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
e570: 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
e580: 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72  ibility consider
e590: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65  ations..**.** Re
e5a0: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
e5b0: 48 31 32 32 30 31 5d 20 5b 48 31 32 32 30 32 5d  H12201] [H12202]
e5c0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
e5d0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
e5e0: 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
e5f0: 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
e600: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
e610: 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b  t Insert Rowid {
e620: 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30 3e  H12220} <S10700>
e630: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72  .**.** Each entr
e640: 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
e650: 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
e660: 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
e670: 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
e680: 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
e690: 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 54 68 65   | "rowid"]. The
e6a0: 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
e6b0: 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
e6c0: 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
e6d0: 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
e6e0: 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
e6f0: 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
e700: 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
e710: 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
e720: 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
e730: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49  lared columns. I
e740: 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
e750: 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
e760: 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
e770: 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
e780: 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
e790: 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
e7a0: 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
e7b0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
e7c0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
e7d0: 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
e7e0: 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
e7f0: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
e800: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
e810: 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
e820: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
e830: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
e840: 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f  argument.  If no
e850: 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
e860: 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76  ERT]s.** have ev
e870: 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
e880: 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
e890: 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
e8a0: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
e8b0: 20 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20   If an [INSERT] 
e8c0: 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
e8d0: 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68  trigger, then th
e8e0: 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
e8f0: 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
e900: 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
e910: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20  this routine as 
e920: 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
e930: 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ger is running..
e940: 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
e950: 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74  trigger terminat
e960: 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
e970: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
e980: 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74  outine.** revert
e990: 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61  s to the last va
e9a0: 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66  lue inserted bef
e9b0: 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
e9c0: 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  fired..**.** An 
e9d0: 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
e9e0: 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
e9f0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
ea00: 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
ea10: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
ea20: 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
ea30: 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
ea40: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
ea50: 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68  .** routine.  Th
ea60: 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
ea70: 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
ea80: 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
ea90: 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
eaa0: 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
eab0: 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
eac0: 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
ead0: 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
eae0: 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
eaf0: 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
eb00: 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20  s.  When INSERT 
eb10: 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
eb20: 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
eb30: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
eb40: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
eb50: 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
eb60: 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
eb70: 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
eb80: 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
eb90: 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
eba0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
ebb0: 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
ebc0: 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
ebd0: 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
ebe0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
ebf0: 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
ec00: 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  e..**.** For the
ec10: 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
ec20: 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
ec30: 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
ec40: 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
ec50: 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
ec60: 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
ec70: 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
ec80: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
ec90: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 5d  nts:.** [H12221]
eca0: 20 5b 48 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20   [H12223].**.** 
ecb0: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
ecc0: 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
ecd0: 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
ece0: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
ecf0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
ed00: 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
ed10: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
ed20: 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
ed30: 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
ed40: 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
ed50: 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
ed60: 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
ed70: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
ed80: 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
ed90: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
eda0: 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
edb0: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
edc0: 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
edd0: 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
ede0: 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
edf0: 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
ee00: 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
ee10: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
ee20: 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
ee30: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
ee40: 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
ee50: 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
ee60: 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d  odified {H12240}
ee70: 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10600>.**.** 
ee80: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
ee90: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
eea0: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
eeb0: 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
eec0: 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
eed0: 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
eee0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
eef0: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
ef00: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
ef10: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
ef20: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
ef30: 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
ef40: 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
ef50: 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
ef60: 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
ef70: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
ef80: 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
ef90: 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
efa0: 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
efb0: 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
efc0: 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
efd0: 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
efe0: 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b  rs or [foreign k
eff0: 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
f000: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65  not counted. Use
f010: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
f020: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
f030: 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69  ] function to fi
f040: 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
f050: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a  ber of changes.*
f060: 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e  * including chan
f070: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72  ges caused by tr
f080: 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69  iggers and forei
f090: 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a  gn key actions..
f0a0: 2a 2a 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f  **.** Changes to
f0b0: 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
f0c0: 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
f0d0: 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
f0e0: 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
f0f0: 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
f100: 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
f110: 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
f120: 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61  **.** A "row cha
f130: 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65  nge" is a change
f140: 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
f150: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
f160: 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
f170: 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
f180: 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
f190: 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
f1a0: 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
f1b0: 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
f1c0: 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63  s of [REPLACE] c
f1d0: 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
f1e0: 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63  tion,.** rollbac
f1f0: 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  k, ABORT process
f200: 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45  ing, [DROP TABLE
f210: 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  ], or by any oth
f220: 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
f230: 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
f240: 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
f250: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  ges..**.** A "tr
f260: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
f270: 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
f280: 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
f290: 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
f2a0: 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
f2b0: 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47  f a [CREATE TRIG
f2c0: 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20  GER | trigger]. 
f2d0: 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  .** Most SQL sta
f2e0: 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
f2f0: 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
f300: 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
f310: 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
f320: 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
f330: 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
f340: 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
f350: 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
f360: 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
f370: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
f380: 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
f390: 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
f3a0: 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
f3b0: 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
f3c0: 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
f3d0: 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
f3e0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  ation..**.** Cal
f3f0: 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
f400: 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
f410: 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
f420: 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
f430: 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
f440: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
f450: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
f460: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
f470: 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
f480: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
f490: 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
f4a0: 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
f4b0: 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
f4c0: 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
f4d0: 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
f4e0: 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
f4f0: 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c   Thus, when call
f500: 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
f510: 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
f520: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
f530: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
f540: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
f550: 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
f560: 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
f570: 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
f580: 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
f590: 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 74 68  top level.  With
f5a0: 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
f5b0: 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65   trigger,.** the
f5c0: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
f5d0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
f5e0: 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69   be called to fi
f5f0: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
f600: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
f610: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
f620: 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
f630: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
f640: 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
f650: 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
f660: 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72  y of the same tr
f670: 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65  igger..** Howeve
f680: 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65  r, the number re
f690: 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
f6a0: 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a  include changes.
f6b0: 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62  ** caused by sub
f6c0: 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74  triggers since t
f6d0: 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20  hose have their 
f6e0: 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  own context..**.
f6f0: 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
f700: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
f710: 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
f720: 61 63 65 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b  ace and the.** [
f730: 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
f740: 61 67 6d 61 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  agma]..**.** Req
f750: 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
f760: 31 32 32 34 31 5d 20 5b 48 31 32 32 34 33 5d 0a  12241] [H12243].
f770: 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
f780: 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
f790: 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
f7a0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
f7b0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
f7c0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
f7d0: 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
f7e0: 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
f7f0: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
f800: 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
f810: 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
f820: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
f830: 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
f840: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
f850: 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
f860: 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
f870: 64 20 7b 48 31 32 32 36 30 7d 20 3c 53 31 30 36  d {H12260} <S106
f880: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  00>.**.** This f
f890: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
f8a0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
f8b0: 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
f8c0: 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a   by [INSERT],.**
f8d0: 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
f8e0: 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
f8f0: 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61   since the [data
f900: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
f910: 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20   was opened..** 
f920: 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64  The count includ
f930: 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66  es all changes f
f940: 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20  rom all [CREATE 
f950: 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
f960: 72 5d 20 0a 2a 2a 20 63 6f 6e 74 65 78 74 73 20  r] .** contexts 
f970: 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
f980: 20 62 79 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   by [foreign key
f990: 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76   actions]. Howev
f9a0: 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
f9b0: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
f9c0: 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
f9d0: 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50  o implement [REP
f9e0: 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
f9f0: 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
fa00: 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
fa10: 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50  essing, or [DROP
fa20: 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69   TABLE] processi
fa30: 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e  ng.  The.** coun
fa40: 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
fa50: 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73  de rows of views
fa60: 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49   that fire an [I
fa70: 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
fa80: 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66  r],.** though if
fa90: 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20   the INSTEAD OF 
faa0: 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68  trigger makes ch
fab0: 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e  anges of its own
fac0: 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  , those changes 
fad0: 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  .** are counted.
fae0: 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20  .** The changes 
faf0: 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73  are counted as s
fb00: 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 65  oon as the state
fb10: 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
fb20: 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c  them is.** compl
fb30: 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73  eted (when the s
fb40: 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
fb50: 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
fb60: 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
fb70: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
fb80: 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
fb90: 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
fba0: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
fbb0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
fbc0: 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
fbd0: 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2e 0a  hanges pragma]..
fbe0: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
fbf0: 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 36 31 5d 20  ts:.** [H12261] 
fc00: 5b 48 31 32 32 36 33 5d 0a 2a 2a 0a 2a 2a 20 49  [H12263].**.** I
fc10: 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
fc20: 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
fc30: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
fc40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fc50: 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
fc60: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
fc70: 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
fc80: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
fc90: 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
fca0: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
fcb0: 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
fcc0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
fcd0: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
fce0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
fcf0: 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
fd00: 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
fd10: 67 20 51 75 65 72 79 20 7b 48 31 32 32 37 30 7d  g Query {H12270}
fd20: 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30500>.**.** 
fd30: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
fd40: 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
fd50: 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
fd60: 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
fd70: 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
fd80: 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
fd90: 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
fda0: 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
fdb0: 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
fdc0: 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
fdd0: 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
fde0: 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
fdf0: 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
fe00: 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
fe10: 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
fe20: 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
fe30: 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
fe40: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ly..**.** It is 
fe50: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
fe60: 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
fe70: 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
fe80: 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
fe90: 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
fea0: 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
feb0: 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
fec0: 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
fed0: 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
fee0: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
fef0: 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
ff00: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
ff10: 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
ff20: 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
ff30: 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
ff40: 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
ff50: 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  rns..**.** If an
ff60: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
ff70: 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
ff80: 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
ff90: 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
ffa0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
ffb0: 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
ffc0: 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
ffd0: 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
ffe0: 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
fff0: 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
10000 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
10010 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  etion..**.** An 
10020 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
10030 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
10040 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
10050 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
10060 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65  ..** If the inte
10070 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
10080 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
10090 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
100a0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
100b0 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
100c0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
100d0 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
100e0 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
100f0 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
10100 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
10110 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
10120 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
10130 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
10140 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
10150 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
10160 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
10170 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
10180 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
10190 70 6c 65 74 65 2e 20 20 41 6e 79 20 6e 65 77 20  plete.  Any new 
101a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
101b0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
101c0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
101d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
101e0 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
101f0 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
10200 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
10210 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
10220 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
10230 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
10240 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
10250 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
10260 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
10270 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
10280 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
10290 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
102a0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
102b0 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
102c0 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
102d0 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
102e0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
102f0 70 74 28 29 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20  pt()..** A call 
10300 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
10310 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
10320 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
10330 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
10340 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
10350 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
10360 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
10370 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
10380 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
10390 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
103a0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
103b0 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
103c0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
103d0 73 3a 0a 2a 2a 20 5b 48 31 32 32 37 31 5d 20 5b  s:.** [H12271] [
103e0 48 31 32 32 37 32 5d 0a 2a 2a 0a 2a 2a 20 49 66  H12272].**.** If
103f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
10400 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
10410 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
10420 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
10430 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
10440 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
10450 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
10460 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
10470 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
10480 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10490 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
104a0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
104b0 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 48  t Is Complete {H
104c0 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30 3e 0a  10510} <S70200>.
104d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
104e0 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
104f0 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
10500 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
10510 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
10520 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
10530 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
10540 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
10550 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
10560 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
10570 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
10580 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
10590 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
105a0 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
105b0 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f  rsing.  These ro
105c0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
105d0 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
105e0 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
105f0 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
10600 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
10610 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
10620 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
10630 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
10640 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
10650 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
10660 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
10670 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
10680 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
10690 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d   statement.  Sem
106a0 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
106b0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
106c0 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
106d0 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
106e0 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
106f0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
10700 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
10710 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
10720 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
10730 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
10740 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
10750 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
10760 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
10770 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
10780 74 6f 72 2e 20 20 57 68 69 74 65 73 70 61 63 65  tor.  Whitespace
10790 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
107a0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
107b0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
107c0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
107d0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
107e0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
107f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
10800 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 49 66 20  incomplete.  If 
10810 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
10820 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
10830 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
10840 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
10850 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
10860 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
10870 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
10880 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
10890 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
108a0 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
108b0 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  t SQL..**.** If 
108c0 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
108d0 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
108e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
108f0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
10900 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
10910 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
10920 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
10930 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10940 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
10950 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
10960 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
10970 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
10980 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
10990 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
109a0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
109b0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
109c0 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
109d0 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
109e0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
109f0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
10a00 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
10a10 65 74 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ete..**.** Requi
10a20 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 31 31  rements: [H10511
10a30 5d 20 5b 48 31 30 35 31 32 5d 0a 2a 2a 0a 2a 2a  ] [H10512].**.**
10a40 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
10a50 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
10a60 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
10a70 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
10a80 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
10a90 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
10aa0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
10ab0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
10ac0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
10ad0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
10ae0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
10af0 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
10b00 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
10b10 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
10b20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
10b30 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
10b40 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
10b50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
10b60 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
10b70 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
10b80 45 5f 42 55 53 59 20 45 72 72 6f 72 73 20 7b 48  E_BUSY Errors {H
10b90 31 32 33 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a  12310} <S40400>.
10ba0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
10bb0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
10bc0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
10bd0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
10be0 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  d whenever.** an
10bf0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
10c00 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
10c10 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61  ase table that a
10c20 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
10c30 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
10c40 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  locked..**.** If
10c50 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
10c60 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
10c70 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
10c80 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
10c90 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
10ca0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
10cb0 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
10cc0 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
10cd0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
10ce0 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
10cf0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
10d00 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69  llback will be i
10d10 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
10d20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
10d30 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
10d40 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c  ent to the handl
10d50 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
10d60 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
10d70 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
10d80 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
10d90 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
10da0 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 54 68 65  _handler().  The
10db0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10dc0 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c   to.** the handl
10dd0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
10de0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
10df0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
10e00 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
10e10 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
10e20 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
10e30 65 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20  ent.  If the.** 
10e40 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
10e50 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
10e60 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
10e70 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
10e80 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
10e90 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
10ea0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
10eb0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
10ec0 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
10ed0 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62  .** If the callb
10ee0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
10ef0 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
10f00 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
10f10 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
10f20 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
10f30 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63  eading and the c
10f40 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
10f50 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
10f60 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
10f70 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
10f80 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
10f90 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
10fa0 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
10fb0 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
10fc0 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
10fd0 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
10fe0 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
10ff0 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
11000 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
11010 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
11020 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
11030 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
11040 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
11050 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
11060 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
11070 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
11080 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
11090 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
110a0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
110b0 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
110c0 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
110d0 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
110e0 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
110f0 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
11100 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
11110 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
11120 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
11130 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
11140 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
11150 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
11160 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
11170 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
11180 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
11190 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
111a0 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
111b0 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
111c0 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
111d0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
111e0 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
111f0 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
11200 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
11210 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
11220 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
11230 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
11240 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
11250 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
11260 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
11270 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
11280 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
11290 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
112a0 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
112b0 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
112c0 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
112d0 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
112e0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
112f0 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
11300 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75  * The default bu
11310 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
11320 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ULL..**.** The [
11330 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
11340 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
11350 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
11360 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
11370 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
11380 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
11390 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
113a0 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
113b0 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
113c0 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
113d0 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
113e0 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
113f0 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
11400 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
11410 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
11420 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
11430 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
11440 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
11450 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
11460 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
11470 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
11480 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
11490 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
114a0 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
114b0 65 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69  eaders.  If it i
114c0 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
114d0 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
114e0 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
114f0 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
11500 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
11510 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
11520 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
11530 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
11540 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
11550 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
11560 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
11570 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
11580 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
11590 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69  R_BLOCKED].  Thi
115a0 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
115b0 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
115c0 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
115d0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
115e0 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
115f0 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73  ** <a href="/cvs
11600 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72  trac/wiki?p=Corr
11610 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
11620 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f  usyError">.** Co
11630 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
11640 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77  gBusyError</a> w
11650 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64  iki page for a d
11660 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79  iscussion of why
11670 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f  .** this is impo
11680 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rtant..**.** The
11690 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
116a0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
116b0 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
116c0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
116d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
116e0 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
116f0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
11700 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
11710 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
11720 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c  .  Note that cal
11730 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
11740 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
11750 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
11760 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79  r clear the busy
11770 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
11780 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
11790 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
117a0 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
117b0 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
117c0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
117d0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
117e0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
117f0 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ler.  Any such a
11800 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
11810 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
11820 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 52  havior..** .** R
11830 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
11840 5b 48 31 32 33 31 31 5d 20 5b 48 31 32 33 31 32  [H12311] [H12312
11850 5d 20 5b 48 31 32 33 31 34 5d 20 5b 48 31 32 33  ] [H12314] [H123
11860 31 36 5d 20 5b 48 31 32 33 31 38 5d 0a 2a 2a 0a  16] [H12318].**.
11870 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
11880 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
11890 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
118a0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
118b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
118c0 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
118d0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
118e0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
118f0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
11900 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
11910 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
11920 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
11930 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
11940 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34 30 7d  Timeout {H12340}
11950 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S40410>.**.** 
11960 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
11970 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
11980 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
11990 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
119a0 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
119b0 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
119c0 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
119d0 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
119e0 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20   The handler.** 
119f0 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
11a00 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
11a10 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
11a20 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
11a30 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
11a40 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31 32  ccumulated. {H12
11a50 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73 22 20  343} After "ms" 
11a60 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
11a70 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
11a80 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
11a90 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
11aa0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
11ab0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
11ac0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
11ad0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
11ae0 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  CKED]..**.** Cal
11af0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
11b00 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
11b10 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
11b20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
11b30 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
11b40 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
11b50 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e  .** There can on
11b60 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
11b70 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
11b80 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
11b90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11ba0 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69  tion] any any gi
11bb0 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
11bc0 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
11bd0 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
11be0 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
11bf0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
11c00 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
11c10 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
11c20 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
11c30 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
11c40 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a  is cleared..**.*
11c50 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
11c60 2a 2a 20 5b 48 31 32 33 34 31 5d 20 5b 48 31 32  ** [H12341] [H12
11c70 33 34 33 5d 20 5b 48 31 32 33 34 34 5d 0a 2a 2f  343] [H12344].*/
11c80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
11c90 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
11ca0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
11cb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
11cc0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
11cd0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
11ce0 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20  ueries {H12370} 
11cf0 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44  <S10000>.**.** D
11d00 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
11d10 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
11d20 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
11d30 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
11d40 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
11d50 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
11d60 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
11d70 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
11d80 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
11d90 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
11da0 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
11db0 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
11dc0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
11dd0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
11de0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
11df0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
11e00 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
11e10 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
11e20 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
11e30 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
11e40 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
11e50 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
11e60 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
11e70 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
11e80 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
11e90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
11ea0 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
11eb0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
11ec0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
11ed0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
11ee0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
11ef0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
11f00 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
11f10 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
11f20 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
11f30 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
11f40 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
11f50 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
11f60 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
11f70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
11f80 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
11f90 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
11fa0 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
11fb0 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
11fc0 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
11fd0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
11fe0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
11ff0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
12000 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
12010 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
12020 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
12030 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
12040 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
12050 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
12060 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
12070 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
12080 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
12090 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
120a0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
120b0 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
120c0 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
120d0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
120e0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
120f0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
12100 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
12110 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
12120 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
12130 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
12140 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
12150 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
12160 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
12170 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
12180 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
12190 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
121a0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
121b0 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
121c0 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
121d0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
121e0 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
121f0 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
12200 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
12210 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
12220 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
12230 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
12240 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
12250 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
12260 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
12270 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
12280 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
12290 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
122a0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
122b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
122c0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
122d0 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
122e0 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
122f0 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
12300 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
12310 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12320 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
12330 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
12340 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
12350 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
12360 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
12370 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
12380 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
12390 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
123a0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
123b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
123c0 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
123d0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
123e0 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
123f0 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
12400 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
12410 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
12420 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
12430 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
12440 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
12450 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
12460 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
12470 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
12480 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
12490 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
124a0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
124b0 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
124c0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
124d0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
124e0 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
124f0 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20  .  It returns a 
12500 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
12510 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
12520 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
12530 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
12540 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69   After the calli
12550 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20  ng function has 
12560 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
12570 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68  he result, it sh
12580 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65  ould.** pass the
12590 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
125a0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
125b0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
125c0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
125d0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
125e0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
125f0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
12600 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
12610 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
12620 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
12630 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
12640 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
12650 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
12660 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
12670 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
12680 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
12690 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
126a0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
126b0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
126c0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
126d0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
126e0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
126f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
12700 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
12710 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
12720 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
12730 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
12740 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
12750 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
12760 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
12770 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
12780 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
12790 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
127a0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
127b0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
127c0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
127d0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
127e0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
127f0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
12800 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
12810 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
12820 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
12830 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
12840 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
12850 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
12860 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
12870 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
12880 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71  rrcode()] or [sq
12890 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
128a0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
128b0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 37 31 5d  nts:.** [H12371]
128c0 20 5b 48 31 32 33 37 33 5d 20 5b 48 31 32 33 37   [H12373] [H1237
128d0 34 5d 20 5b 48 31 32 33 37 36 5d 20 5b 48 31 32  4] [H12376] [H12
128e0 33 37 39 5d 20 5b 48 31 32 33 38 32 5d 0a 2a 2f  379] [H12382].*/
128f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
12900 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
12910 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
12920 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
12930 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
12940 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
12950 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
12960 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
12970 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
12980 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
12990 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
129a0 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
129b0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
129c0 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
129d0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
129e0 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
129f0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
12a00 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
12a10 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
12a20 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
12a30 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
12a40 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
12a50 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
12a60 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
12a70 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
12a80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12a90 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
12aa0 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
12ab0 74 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c  tions {H17400} <
12ac0 53 37 30 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a  S70000><S20000>.
12ad0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
12ae0 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c  ines are work-al
12af0 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
12b00 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
12b10 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
12b20 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
12b30 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
12b40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72   The sqlite3_mpr
12b50 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
12b60 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
12b70 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
12b80 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
12b90 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
12ba0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
12bb0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
12bc0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
12bd0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
12be0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
12bf0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
12c00 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
12c10 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69  ()].  Both routi
12c20 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
12c30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
12c40 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12c50 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
12c60 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
12c70 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
12c80 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
12c90 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e  string..**.** In
12ca0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
12cb0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
12cc0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
12cd0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
12ce0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
12cf0 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
12d00 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
12d10 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
12d20 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
12d30 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
12d40 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
12d50 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
12d60 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
12d70 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
12d80 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
12d90 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
12da0 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
12db0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
12dc0 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
12dd0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
12de0 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
12df0 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
12e00 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
12e10 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
12e20 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f  lity.  Note also
12e30 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
12e40 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
12e50 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
12e60 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
12e70 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
12e80 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
12e90 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
12ea0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
12eb0 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74  fer.  We admit t
12ec0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
12ed0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
12ee0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
12ef0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
12f00 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
12f10 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
12f20 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
12f30 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
12f40 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
12f50 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
12f60 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
12f70 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e  ty..**.** As lon
12f80 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
12f90 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
12fa0 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
12fb0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
12fc0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
12fd0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
12fe0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
12ff0 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 73  nated.  The firs
13000 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
13010 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
13020 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
13030 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
13040 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
13050 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
13060 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
13070 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
13080 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
13090 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
130a0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
130b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
130c0 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
130d0 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
130e0 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
130f0 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
13100 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
13110 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
13120 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
13130 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
13140 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
13150 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
13160 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
13170 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
13180 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
13190 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
131a0 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f  .** The %q optio
131b0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
131c0 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
131d0 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65  itutes a null-te
131e0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
131f0 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
13200 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
13210 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
13220 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
13230 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
13240 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
13250 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
13260 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75  literal.  By dou
13270 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
13280 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
13290 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
132a0 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
132b0 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
132c0 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
132d0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
132e0 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
132f0 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
13300 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
13310 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
13320 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
13330 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
13340 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
13350 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
13360 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
13370 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
13380 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
13390 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
133a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
133b0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
133c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
133d0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
133e0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
133f0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
13400 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
13410 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
13420 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
13430 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
13440 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
13450 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
13460 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
13470 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
13480 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
13490 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
134a0 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
134b0 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
134c0 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
134d0 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
134e0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
134f0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
13500 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
13510 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
13520 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
13530 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
13540 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
13550 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
13560 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
13570 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
13580 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
13590 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
135a0 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
135b0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
135c0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
135d0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
135e0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
135f0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
13600 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
13610 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
13620 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
13630 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
13640 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
13650 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
13660 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
13670 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
13680 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
13690 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
136a0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
136b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f  ..**.** The %Q o
136c0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
136d0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
136e0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
136f0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
13700 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
13710 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
13720 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
13730 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
13740 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
13750 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
13760 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
13770 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
13780 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
13790 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
137a0 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f  otes) in place o
137b0 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e  f the %Q option.
137c0 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
137d0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
137e0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
137f0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
13800 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
13810 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
13820 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
13830 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
13840 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
13850 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
13860 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
13870 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
13880 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
13890 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
138a0 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
138b0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
138c0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
138d0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
138e0 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
138f0 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
13900 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
13910 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
13920 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
13930 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61  option works exa
13940 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77  ctly like "%s" w
13950 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
13960 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
13970 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
13980 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
13990 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
139a0 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
139b0 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
139c0 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
139d0 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  tring. {END}.**.
139e0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
139f0 0a 2a 2a 20 5b 48 31 37 34 30 33 5d 20 5b 48 31  .** [H17403] [H1
13a00 37 34 30 36 5d 20 5b 48 31 37 34 30 37 5d 0a 2a  7406] [H17407].*
13a10 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
13a20 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
13a30 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
13a40 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
13a50 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
13a60 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
13a70 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
13a80 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
13a90 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  har*, ...);../*.
13aa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
13ab0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
13ac0 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30  ubsystem {H17300
13ad0 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20000>.**.**
13ae0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
13af0 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72    uses these thr
13b00 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
13b10 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
13b20 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
13b30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
13b40 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
13b50 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
13b60 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
13b70 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
13b80 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
13b90 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
13ba0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
13bb0 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
13bc0 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
13bd0 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
13be0 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
13bf0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
13c00 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
13c10 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
13c20 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
13c30 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
13c40 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
13c50 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
13c60 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
13c70 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  ..** If sqlite3_
13c80 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
13c90 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
13ca0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
13cb0 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
13cc0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
13cd0 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d  r.  If the param
13ce0 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
13cf0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
13d00 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
13d10 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
13d20 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
13d30 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
13d40 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  r..**.** Calling
13d50 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
13d60 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
13d70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
13d80 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
13d90 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
13da0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
13db0 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
13dc0 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
13dd0 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
13de0 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
13df0 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
13e00 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
13e10 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
13e20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
13e30 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
13e40 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
13e50 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
13e60 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
13e70 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
13e80 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
13e90 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
13ea0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
13eb0 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
13ec0 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
13ed0 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
13ee0 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
13ef0 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
13f00 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
13f10 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
13f20 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
13f30 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
13f40 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
13f50 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
13f60 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
13f70 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
13f80 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
13f90 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
13fa0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
13fb0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
13fc0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
13fd0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
13fe0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61   The sqlite3_rea
13ff0 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65  lloc() interface
14000 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
14010 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
14020 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14030 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
14040 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e  N bytes, where N
14050 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e   is the.** secon
14060 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
14070 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
14080 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65  ion to be resize
14090 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  d is the first.*
140a0 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  * parameter.  If
140b0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
140c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
140d0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
140e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
140f0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
14100 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
14110 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
14120 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
14130 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
14140 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
14150 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14160 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65  ()..** If the se
14170 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
14180 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
14190 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  c() is zero or.*
141a0 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
141b0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
141c0 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
141d0 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
141e0 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77  qlite3_free(P) w
141f0 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69  here P is the fi
14200 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
14210 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14220 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  ()..** sqlite3_r
14230 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
14240 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
14250 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14260 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
14270 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
14280 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
14290 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
142a0 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
142b0 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a   If M is the siz
142c0 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
142d0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
142e0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
142f0 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
14300 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
14310 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
14320 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
14330 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
14340 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14350 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
14360 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
14370 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69  reed..** If sqli
14380 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
14390 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
143a0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
143b0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
143c0 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  freed..**.** The
143d0 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
143e0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
143f0 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  oc() and sqlite3
14400 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
14410 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
14420 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
14430 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20   byte boundary. 
14440 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  {END}.**.** The 
14450 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e  default implemen
14460 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65  tation of the me
14470 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14480 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a  subsystem uses.*
14490 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20  * the malloc(), 
144a0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
144b0 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79  ee() provided by
144c0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
144d0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37  library..** {H17
144e0 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66  382} However, if
144f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14500 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
14510 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49  SQLITE_MEMORY_SI
14520 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20  ZE=<i>NNN</i> C 
14530 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
14540 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e  ro (where <i>NNN
14550 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e  </i>.** is an in
14560 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c  teger), then SQL
14570 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74 61  ite create a sta
14580 74 69 63 20 61 72 72 61 79 20 6f 66 20 61 74 20  tic array of at 
14590 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c  least.** <i>NNN<
145a0 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  /i> bytes in siz
145b0 65 20 61 6e 64 20 75 73 65 73 20 74 68 61 74 20  e and uses that 
145c0 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66  array for all of
145d0 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20   its dynamic.** 
145e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
145f0 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20  n needs. {END}  
14600 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72  Additional memor
14610 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69  y allocator opti
14620 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64  ons.** may be ad
14630 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
14640 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e  leases..**.** In
14650 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
14660 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
14670 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
14680 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
14690 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
146a0 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
146b0 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
146c0 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
146d0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
146e0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
146f0 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
14700 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
14710 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
14720 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
14730 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
14740 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
14750 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
14760 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   The Windows OS 
14770 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
14780 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73  calls.** the sys
14790 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
147a0 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
147b0 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
147c0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
147d0 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
147e0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
147f0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
14800 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
14810 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
14820 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
14830 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
14840 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
14850 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14860 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63  errors are detec
14870 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
14880 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61   are reported ba
14890 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
148a0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
148b0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
148c0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
148d0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52  _NOMEM]..**.** R
148e0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
148f0 5b 48 31 37 33 30 33 5d 20 5b 48 31 37 33 30 34  [H17303] [H17304
14900 5d 20 5b 48 31 37 33 30 35 5d 20 5b 48 31 37 33  ] [H17305] [H173
14910 30 36 5d 20 5b 48 31 37 33 31 30 5d 20 5b 48 31  06] [H17310] [H1
14920 37 33 31 32 5d 20 5b 48 31 37 33 31 35 5d 20 5b  7312] [H17315] [
14930 48 31 37 33 31 38 5d 0a 2a 2a 20 5b 48 31 37 33  H17318].** [H173
14940 32 31 5d 20 5b 48 31 37 33 32 32 5d 20 5b 48 31  21] [H17322] [H1
14950 37 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  7323].**.** The 
14960 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
14970 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
14980 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
14990 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
149a0 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
149b0 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
149c0 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
149d0 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
149e0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
149f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
14a00 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
14a10 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
14a20 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
14a30 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
14a40 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
14a50 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
14a60 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
14a70 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
14a80 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
14a90 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
14aa0 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
14ab0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
14ac0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
14ad0 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
14ae0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
14af0 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
14b00 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
14b10 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
14b20 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
14b30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14b40 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
14b50 6f 72 20 53 74 61 74 69 73 74 69 63 73 20 7b 48  or Statistics {H
14b60 31 37 33 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a  17370} <S30210>.
14b70 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
14b80 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
14b90 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
14ba0 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
14bb0 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
14bc0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14bd0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
14be0 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
14bf0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
14c00 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
14c10 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
14c20 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
14c30 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
14c40 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
14c50 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 37 31 5d  nts:.** [H17371]
14c60 20 5b 48 31 37 33 37 33 5d 20 5b 48 31 37 33 37   [H17373] [H1737
14c70 34 5d 20 5b 48 31 37 33 37 35 5d 0a 2a 2f 0a 73  4] [H17375].*/.s
14c80 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
14c90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
14ca0 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
14cb0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
14cc0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
14cd0 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
14ce0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14cf0 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
14d00 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b  mber Generator {
14d10 48 31 37 33 39 30 7d 20 3c 53 32 30 30 30 30 3e  H17390} <S20000>
14d20 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
14d30 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
14d40 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
14d50 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
14d60 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
14d70 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
14d80 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
14d90 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
14da0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
14db0 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
14dc0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
14dd0 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
14de0 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
14df0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
14e00 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
14e10 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
14e20 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
14e30 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
14e40 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
14e50 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
14e60 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
14e70 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
14e80 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
14e90 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  rposes..**.** A 
14ea0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
14eb0 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79  tine stores N by
14ec0 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
14ed0 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
14ee0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
14ef0 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
14f00 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65  ne is invoked (e
14f10 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79  ither internally
14f20 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70   or by.** the ap
14f30 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50  plication) the P
14f40 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
14f50 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
14f60 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
14f70 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
14f80 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
14f90 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
14fa0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f  fs] object..** O
14fb0 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  n all subsequent
14fc0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68   invocations, th
14fd0 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
14fe0 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
14ff0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
15000 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
15010 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
15020 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
15030 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
15040 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
15050 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 39 32 5d 0a  ts:.** [H17392].
15060 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
15070 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
15080 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
15090 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
150a0 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
150b0 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
150c0 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 37 30 31  s {H12500} <S701
150d0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
150e0 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
150f0 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   a authorizer ca
15100 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
15110 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
15120 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15130 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
15140 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15150 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  t..** The author
15160 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
15170 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
15180 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
15190 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
151a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
151b0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
151c0 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
151d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
151e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
151f0 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
15200 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
15210 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f  v2()].  At vario
15220 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
15230 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
15240 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
15250 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
15260 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
15270 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
15280 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
15290 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
152a0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
152b0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
152c0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
152d0 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72    The authorizer
152e0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
152f0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
15300 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
15310 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
15320 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
15330 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
15340 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
15350 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
15360 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
15370 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
15380 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
15390 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
153a0 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
153b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
153c0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
153d0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 49  ith an error.  I
153e0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
153f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
15400 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
15410 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
15420 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
15430 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
15440 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
15450 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
15460 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
15470 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
15480 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
15490 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
154a0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
154b0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
154c0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
154d0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
154e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
154f0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
15500 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
15510 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e  ted is ok.  When
15520 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
15530 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
15540 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
15550 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
15560 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
15570 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
15580 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
15590 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
155a0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
155b0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
155c0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
155d0 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
155e0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
155f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
15600 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15610 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
15620 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
15630 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
15640 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
15650 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
15660 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
15670 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
15680 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
15690 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
156a0 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
156b0 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
156c0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
156d0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
156e0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65   authorized. The
156f0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
15700 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
15710 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
15720 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
15730 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
15740 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
15750 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
15760 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
15770 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
15780 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  zed..**.** If th
15790 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
157a0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
157b0 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
157c0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
157d0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
157e0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
157f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
15800 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
15810 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
15820 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
15830 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
15840 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
15850 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
15860 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
15870 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
15880 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
15890 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
158a0 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
158b0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
158c0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
158d0 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
158e0 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
158f0 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
15900 2a 2a 20 49 66 20 74 68 65 20 61 63 74 69 6f 6e  ** If the action
15910 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
15920 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
15930 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
15940 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
15950 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
15960 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
15970 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
15980 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
15990 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
159a0 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
159b0 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
159c0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
159d0 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
159e0 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
159f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
15a00 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
15a10 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
15a20 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
15a30 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
15a40 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
15a50 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
15a60 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
15a70 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
15a80 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
15a90 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
15aa0 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
15ab0 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
15ac0 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
15ad0 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
15ae0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
15af0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
15b00 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
15b10 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
15b20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
15b30 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
15b40 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
15b50 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
15b60 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
15b70 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
15b80 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
15b90 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
15ba0 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
15bb0 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
15bc0 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
15bd0 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
15be0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
15bf0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
15c00 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
15c10 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
15c20 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
15c30 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
15c40 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
15c50 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
15c60 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
15c70 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
15c80 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
15c90 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
15ca0 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
15cb0 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
15cc0 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
15cd0 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
15ce0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
15cf0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
15d00 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
15d10 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
15d20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
15d30 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
15d40 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
15d50 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
15d60 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e  **.** Only a sin
15d70 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
15d80 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
15d90 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
15da0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
15db0 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
15dc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
15dd0 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
15de0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
15df0 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61  ious call.  Disa
15e00 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
15e10 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
15e20 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
15e30 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
15e40 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
15e50 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
15e60 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
15e70 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
15e80 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
15e90 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
15ea0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
15eb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
15ec0 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
15ed0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
15ee0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
15ef0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
15f00 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
15f10 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
15f20 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
15f30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15f40 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
15f50 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
15f60 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
15f70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73  h..**.** When [s
15f80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
15f90 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
15fa0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
15fb0 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
15fc0 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
15fd0 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
15fe0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
15ff0 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
16000 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
16010 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
16020 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
16030 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
16040 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
16050 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
16060 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
16070 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
16080 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
16090 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61   Note that the a
160a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
160b0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
160c0 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
160d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
160e0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
160f0 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
16100 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
16110 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
16120 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
16130 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
16140 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
16150 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
16160 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
16170 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
16180 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
16190 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
161a0 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
161b0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
161c0 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
161d0 67 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ge..**.** Requir
161e0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 35  ements:.** [H125
161f0 30 31 5d 20 5b 48 31 32 35 30 32 5d 20 5b 48 31  01] [H12502] [H1
16200 32 35 30 33 5d 20 5b 48 31 32 35 30 34 5d 20 5b  2503] [H12504] [
16210 48 31 32 35 30 35 5d 20 5b 48 31 32 35 30 36 5d  H12505] [H12506]
16220 20 5b 48 31 32 35 30 37 5d 20 5b 48 31 32 35 31   [H12507] [H1251
16230 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 31 5d 20 5b  0].** [H12511] [
16240 48 31 32 35 31 32 5d 20 5b 48 31 32 35 32 30 5d  H12512] [H12520]
16250 20 5b 48 31 32 35 32 31 5d 20 5b 48 31 32 35 32   [H12521] [H1252
16260 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  2].*/.int sqlite
16270 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
16280 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
16290 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
162a0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
162b0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
162c0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
162d0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
162e0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
162f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
16300 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
16310 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20   Codes {H12590} 
16320 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12500>.**.** T
16330 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
16340 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
16350 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
16360 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
16370 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
16380 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
16390 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
163a0 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
163b0 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
163c0 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
163d0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
163e0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
163f0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
16400 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
16410 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
16420 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
16430 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
16440 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
16450 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16460 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
16470 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
16480 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
16490 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
164a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
164b0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
164c0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
164d0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
164e0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
164f0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
16500 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
16510 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30   {H12550} <H1250
16520 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0>.**.** The [sq
16530 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
16540 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
16550 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
16560 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
16570 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
16580 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
16590 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
165a0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
165b0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
165c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
165d0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
165e0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
165f0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
16600 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
16610 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
16620 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
16630 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
16640 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
16650 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16660 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
16670 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
16680 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
16690 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
166a0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
166b0 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
166c0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
166d0 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
166e0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
166f0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
16700 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
16710 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
16720 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
16730 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
16740 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
16750 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
16760 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
16770 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
16780 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
16790 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
167a0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
167b0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
167c0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
167d0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
167e0 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72  le.  The 6th par
167f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
16800 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16810 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
16820 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
16830 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
16840 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
16850 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
16860 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
16870 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
16880 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
16890 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
168a0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
168b0 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 52 65  L code..**.** Re
168c0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
168d0 48 31 32 35 35 31 5d 20 5b 48 31 32 35 35 32 5d  H12551] [H12552]
168e0 20 5b 48 31 32 35 35 33 5d 20 5b 48 31 32 35 35   [H12553] [H1255
168f0 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  4].*/./*********
16900 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16910 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16920 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
16930 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
16940 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
16950 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
16960 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
16970 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
16980 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
16990 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
169a0 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
169b0 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
169c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
169d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
169e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
169f0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
16a00 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
16a10 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
16a20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
16a30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16a40 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
16a50 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
16a60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
16a70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
16a80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16a90 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
16aa0 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
16ab0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
16ac0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
16ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16ae0 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
16af0 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
16b00 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
16b10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
16b20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
16b30 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
16b40 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
16b50 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
16b60 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
16b70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
16b80 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
16b90 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
16ba0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
16bb0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
16bc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
16bd0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
16be0 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
16bf0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
16c00 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
16c10 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
16c20 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
16c30 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
16c40 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
16c50 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
16c60 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
16c70 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
16c80 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
16c90 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
16ca0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
16cb0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
16cc0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
16cd0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
16ce0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
16cf0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
16d00 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
16d10 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
16d20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
16d30 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
16d40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
16d50 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
16d60 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
16d70 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
16d80 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
16d90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16da0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
16db0 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
16dc0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
16dd0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
16de0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16df0 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
16e00 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
16e10 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
16e20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
16e30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
16e40 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
16e50 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
16e60 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
16e70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
16e80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16e90 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
16ea0 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
16eb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
16ec0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
16ed0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16ee0 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
16ef0 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
16f00 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
16f10 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
16f20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16f30 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
16f40 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
16f50 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
16f60 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
16f70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16f80 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
16f90 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
16fa0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
16fb0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
16fc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
16fd0 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
16fe0 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
16ff0 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
17000 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17010 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
17020 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
17030 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
17040 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
17050 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
17060 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
17070 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
17080 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
17090 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
170a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
170b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
170c0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
170d0 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
170e0 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
170f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17100 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
17110 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
17120 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
17130 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
17140 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
17150 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
17160 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
17170 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
17180 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
17190 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
171a0 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
171b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
171c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
171d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
171e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
171f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
17200 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
17210 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
17220 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
17230 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17240 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
17250 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
17260 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
17270 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
17280 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17290 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
172a0 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
172b0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
172c0 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
172d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
172e0 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
172f0 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
17300 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
17310 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
17320 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17330 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
17340 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
17350 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
17360 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
17370 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
17380 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
17390 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53 36  ons {H12280} <S6
173a0 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0400>.** EXPERIM
173b0 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ENTAL.**.** Thes
173c0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
173d0 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
173e0 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
173f0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
17400 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
17410 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
17420 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
17430 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
17440 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
17450 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
17460 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
17470 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
17480 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
17490 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
174a0 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
174b0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
174c0 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61  ep()]..** The ca
174d0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
174e0 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
174f0 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   of the SQL stat
17500 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73  ement text.** as
17510 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
17520 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
17530 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  uting.  Addition
17540 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63  al callbacks occ
17550 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
17560 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
17570 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
17580 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
17590 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
175a0 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
175b0 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
175c0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
175d0 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  igger..**.** The
175e0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
175f0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
17600 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
17610 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
17620 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
17630 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
17640 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61    The profile ca
17650 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
17660 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
17670 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
17680 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
17690 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
176a0 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
176b0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
176c0 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a  took to run..**.
176d0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
176e0 0a 2a 2a 20 5b 48 31 32 32 38 31 5d 20 5b 48 31  .** [H12281] [H1
176f0 32 32 38 32 5d 20 5b 48 31 32 32 38 33 5d 20 5b  2282] [H12283] [
17700 48 31 32 32 38 34 5d 20 5b 48 31 32 32 38 35 5d  H12284] [H12285]
17710 20 5b 48 31 32 32 38 37 5d 20 5b 48 31 32 32 38   [H12287] [H1228
17720 38 5d 20 5b 48 31 32 32 38 39 5d 0a 2a 2a 20 5b  8] [H12289].** [
17730 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 51 4c 49 54  H12290].*/.SQLIT
17740 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
17750 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
17760 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
17770 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
17780 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
17790 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58  oid*);.SQLITE_EX
177a0 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
177b0 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
177c0 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
177d0 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
177e0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
177f0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
17800 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
17810 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
17820 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
17830 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30  ks {H12910} <S60
17840 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  400>.**.** This 
17850 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72  routine configur
17860 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
17870 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20  nction - the.** 
17880 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
17890 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f  k - that is invo
178a0 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
178b0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20   during long.** 
178c0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
178d0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
178e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
178f0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
17900 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
17910 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
17920 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
17930 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
17940 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
17950 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
17960 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  query..**.** If 
17970 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
17980 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
17990 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
179a0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
179b0 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
179c0 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
179d0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
179e0 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
179f0 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
17a00 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
17a10 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
17a20 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75  gress handler mu
17a30 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
17a40 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
17a50 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
17a60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
17a70 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
17a80 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
17a90 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
17aa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17ab0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
17ac0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
17ad0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
17ae0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17af0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
17b00 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
17b10 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
17b20 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ph..**.** Requir
17b30 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39  ements:.** [H129
17b40 31 31 5d 20 5b 48 31 32 39 31 32 5d 20 5b 48 31  11] [H12912] [H1
17b50 32 39 31 33 5d 20 5b 48 31 32 39 31 34 5d 20 5b  2913] [H12914] [
17b60 48 31 32 39 31 35 5d 20 5b 48 31 32 39 31 36 5d  H12915] [H12916]
17b70 20 5b 48 31 32 39 31 37 5d 20 5b 48 31 32 39 31   [H12917] [H1291
17b80 38 5d 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  8].**.*/.void sq
17b90 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
17ba0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
17bb0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
17bc0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
17bd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
17be0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
17bf0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
17c00 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30 30  {H12700} <S40200
17c10 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
17c20 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
17c30 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
17c40 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69  ile whose name i
17c50 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a  s given by the.*
17c60 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
17c70 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d  ent. The filenam
17c80 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
17c90 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
17ca0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
17cb0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
17cc0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
17cd0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
17ce0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
17cf0 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
17d00 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41  ite3_open16(). A
17d10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17d20 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
17d30 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
17d40 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
17d50 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
17d60 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
17d70 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
17d80 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
17d90 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
17da0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
17db0 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
17dc0 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
17dd0 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
17de0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
17df0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
17e00 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
17e10 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
17e20 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  . If the databas
17e30 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
17e40 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
17e50 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
17e60 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
17e70 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
17e80 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
17e90 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
17ea0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ed.  The.** [sql
17eb0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
17ec0 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
17ed0 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
17ee0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
17ef0 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
17f00 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
17f10 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
17f20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
17f30 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
17f40 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
17f50 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
17f60 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
17f70 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
17f80 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
17f90 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
17fa0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
17fb0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
17fc0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
17fd0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
17fe0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
17ff0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
18000 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
18010 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
18020 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
18030 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
18040 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
18050 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
18060 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
18070 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
18080 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
18090 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
180a0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
180b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
180c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
180d0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
180e0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
180f0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
18100 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
18110 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
18120 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
18130 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
18140 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
18150 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67  ction.  The flag
18160 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  s parameter can 
18170 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
18180 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
18190 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
181a0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
181b0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
181c0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
181d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
181e0 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
181f0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
18200 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ACHE],.** and/or
18210 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
18220 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
18230 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  s:.**.** <dl>.**
18240 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
18250 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
18260 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
18270 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
18280 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
18290 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
182a0 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
182b0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
182c0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
182d0 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
182e0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
182f0 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
18300 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
18310 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
18320 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
18330 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
18340 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
18350 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
18360 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
18370 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
18380 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
18390 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
183a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
183b0 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
183c0 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
183d0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
183e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
183f0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
18400 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
18410 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
18420 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18430 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
18440 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
18450 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
18460 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69 66  is creates it if
18470 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
18480 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
18490 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
184a0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
184b0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
184c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
184d0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
184e0 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  ().</dd>.** </dl
184f0 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
18500 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
18510 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
18520 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
18530 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
18540 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
18550 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  or one of the co
18560 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
18570 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a   above combined.
18580 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
18590 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
185a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
185b0 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b  FULLMUTEX],.** [
185c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
185d0 45 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20  EDCACHE] and/or 
185e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
185f0 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 73 2c  REDCACHE] flags,
18600 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
18610 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
18620 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
18630 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
18640 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
18650 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
18660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18670 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
18680 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
18690 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
186a0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
186b0 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
186c0 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
186d0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
186e0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
186f0 6d 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 5b  me.  If the.** [
18700 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
18710 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
18720 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
18730 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18740 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
18750 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
18760 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
18770 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
18780 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
18790 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
187a0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
187b0 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 54 68  tart-time..** Th
187c0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
187d0 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
187e0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
187f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18800 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
18810 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
18820 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
18830 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
18840 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
18850 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
18860 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
18870 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
18880 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 54 68  ed_cache()].  Th
18890 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
188a0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
188b0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
188c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
188d0 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
188e0 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
188f0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
18900 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
18910 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  nabled..**.** If
18920 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
18930 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
18940 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
18950 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
18960 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
18970 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
18980 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69  connection.  Thi
18990 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
189a0 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
189b0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
189c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
189d0 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
189e0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
189f0 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
18a00 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
18a10 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
18a20 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
18a30 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
18a40 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
18a50 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
18a60 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
18a70 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
18a80 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
18a90 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
18aa0 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
18ab0 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
18ac0 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
18ad0 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
18ae0 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
18af0 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
18b00 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e  .** If the filen
18b10 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
18b20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
18b30 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
18b40 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
18b50 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
18b60 65 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69  eated.  This pri
18b70 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
18b80 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
18b90 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
18ba0 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
18bb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18bc0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
18bd0 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
18be0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
18bf0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
18c00 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
18c10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
18c20 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
18c30 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
18c40 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
18c50 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
18c60 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
18c70 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
18c80 73 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72  se.  If the four
18c90 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
18ca0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
18cb0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
18cc0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
18cd0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
18ce0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
18cf0 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
18d00 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
18d10 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
18d20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
18d30 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
18d40 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
18d50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
18d60 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
18d70 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
18d80 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
18d90 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
18da0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
18db0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
18dc0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
18dd0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
18de0 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
18df0 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
18e00 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
18e10 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
18e20 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
18e30 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
18e40 2a 20 5b 48 31 32 37 30 31 5d 20 5b 48 31 32 37  * [H12701] [H127
18e50 30 32 5d 20 5b 48 31 32 37 30 33 5d 20 5b 48 31  02] [H12703] [H1
18e60 32 37 30 34 5d 20 5b 48 31 32 37 30 36 5d 20 5b  2704] [H12706] [
18e70 48 31 32 37 30 37 5d 20 5b 48 31 32 37 30 39 5d  H12707] [H12709]
18e80 20 5b 48 31 32 37 31 31 5d 0a 2a 2a 20 5b 48 31   [H12711].** [H1
18e90 32 37 31 32 5d 20 5b 48 31 32 37 31 33 5d 20 5b  2712] [H12713] [
18ea0 48 31 32 37 31 34 5d 20 5b 48 31 32 37 31 37 5d  H12714] [H12717]
18eb0 20 5b 48 31 32 37 31 39 5d 20 5b 48 31 32 37 32   [H12719] [H1272
18ec0 31 5d 20 5b 48 31 32 37 32 33 5d 0a 2a 2f 0a 69  1] [H12723].*/.i
18ed0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
18ee0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
18ef0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
18f00 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
18f10 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
18f20 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
18f30 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
18f40 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
18f50 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
18f60 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
18f70 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
18f80 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
18f90 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
18fa0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
18fb0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
18fc0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
18fd0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
18fe0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
18ff0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
19000 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
19010 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
19020 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
19030 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
19040 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
19050 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
19060 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
19070 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
19080 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
19090 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
190a0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
190b0 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
190c0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
190d0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
190e0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 48   And Messages {H
190f0 31 32 38 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a  12800} <S60200>.
19100 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
19110 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
19120 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
19130 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
19140 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
19150 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
19160 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
19170 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
19180 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
19190 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
191a0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
191b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
191c0 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
191d0 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
191e0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
191f0 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
19200 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
19210 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
19220 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
19230 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 54  is undefined.  T
19240 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
19250 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
19260 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
19270 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
19280 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
19290 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
192a0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
192b0 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
192c0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
192d0 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
192e0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  led..**.** The s
192f0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
19300 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
19310 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
19320 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
19330 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
19340 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
19350 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
19360 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
19370 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f  ctively..** Memo
19380 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
19390 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
193a0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
193b0 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
193c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
193d0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
193e0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
193f0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
19400 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
19410 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
19420 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
19430 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
19440 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
19450 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
19460 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
19470 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
19480 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
19490 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
194a0 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
194b0 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
194c0 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
194d0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
194e0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
194f0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
19500 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
19510 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
19520 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
19530 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
19540 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
19550 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
19560 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
19570 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
19580 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
19590 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
195a0 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
195b0 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
195c0 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
195d0 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
195e0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
195f0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
19600 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19610 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
19620 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
19630 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
19640 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
19650 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
19660 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
19670 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
19680 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
19690 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
196a0 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
196b0 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
196c0 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
196d0 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
196e0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
196f0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
19700 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
19710 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
19720 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
19730 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
19740 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
19750 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
19760 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
19770 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
19780 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
19790 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
197a0 65 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  et..**.** Requir
197b0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 38  ements:.** [H128
197c0 30 31 5d 20 5b 48 31 32 38 30 32 5d 20 5b 48 31  01] [H12802] [H1
197d0 32 38 30 33 5d 20 5b 48 31 32 38 30 37 5d 20 5b  2803] [H12807] [
197e0 48 31 32 38 30 38 5d 20 5b 48 31 32 38 30 39 5d  H12808] [H12809]
197f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
19800 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
19810 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
19820 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
19830 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
19840 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
19850 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
19860 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
19870 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
19880 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  g16(sqlite3*);..
19890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
198a0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
198b0 6a 65 63 74 20 7b 48 31 33 30 30 30 7d 20 3c 48  ject {H13000} <H
198c0 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  13010>.** KEYWOR
198d0 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
198e0 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
198f0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
19900 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
19910 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
19920 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
19930 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
19940 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
19950 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
19960 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
19970 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
19980 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
19990 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
199a0 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
199b0 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
199c0 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
199d0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
199e0 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
199f0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
19a00 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
19a10 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
19a20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
19a30 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
19a40 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
19a50 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
19a60 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
19a70 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
19a80 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
19a90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
19aa0 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
19ab0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
19ac0 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
19ad0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
19ae0 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
19af0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
19b00 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
19b10 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
19b20 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
19b30 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
19b40 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
19b50 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
19b60 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
19b70 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
19b80 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
19b90 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
19ba0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
19bb0 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
19bc0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
19bd0 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
19be0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
19bf0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
19c00 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
19c10 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
19c20 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
19c30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
19c40 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48  n-time Limits {H
19c50 31 32 37 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a  12760} <S20600>.
19c60 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
19c70 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
19c80 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
19c90 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
19ca0 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
19cb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
19cc0 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
19cd0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
19ce0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
19cf0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19d00 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
19d10 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
19d20 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
19d30 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
19d40 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
19d50 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
19d60 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
19d70 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
19d80 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
19d90 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
19da0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
19db0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
19dc0 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
19dd0 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20  construct.  The 
19de0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
19df0 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a   the old limit..
19e00 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77  **.** If the new
19e10 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
19e20 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
19e30 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
19e40 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20  ged..** For the 
19e50 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f  limit category o
19e60 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58  f SQLITE_LIMIT_X
19e70 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  YZ there is a .*
19e80 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
19e90 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
19ea0 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c   set by a compil
19eb0 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63  e-time C preproc
19ec0 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65  essor macro name
19ed0 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  d .** [limits | 
19ee0 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e  SQLITE_MAX_XYZ].
19ef0 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
19f00 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
19f10 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
19f20 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70  AX_".).** Attemp
19f30 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
19f40 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
19f50 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
19f60 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
19f70 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
19f80 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c 69  he hard upper li
19f90 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74  mit..**.** Run t
19fa0 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
19fb0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
19fc0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
19fd0 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
19fe0 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
19ff0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
1a000 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
1a010 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
1a020 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
1a030 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
1a040 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
1a050 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
1a060 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
1a070 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
1a080 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
1a090 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
1a0a0 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
1a0b0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
1a0c0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
1a0d0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
1a0e0 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
1a0f0 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
1a100 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
1a110 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
1a120 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
1a130 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
1a140 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
1a150 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
1a160 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
1a170 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
1a180 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
1a190 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
1a1a0 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
1a1b0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
1a1c0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
1a1d0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
1a1e0 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
1a1f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1a200 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
1a210 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
1a220 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
1a230 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
1a240 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
1a250 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
1a260 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
1a270 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
1a280 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
1a290 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
1a2a0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
1a2b0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
1a2c0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
1a2d0 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
1a2e0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
1a2f0 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ases..**.** Requ
1a300 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1a310 32 37 36 32 5d 20 5b 48 31 32 37 36 36 5d 20 5b  2762] [H12766] [
1a320 48 31 32 37 36 39 5d 0a 2a 2f 0a 69 6e 74 20 73  H12769].*/.int s
1a330 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
1a340 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
1a350 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
1a360 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1a370 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
1a380 67 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d 20  gories {H12790} 
1a390 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57  <H12760>.** KEYW
1a3a0 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
1a3b0 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61  egory} {limit ca
1a3c0 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
1a3d0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
1a3e0 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
1a3f0 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
1a400 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
1a410 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
1a420 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
1a430 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
1a440 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
1a450 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
1a460 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
1a470 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
1a480 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
1a490 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
1a4a0 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
1a4b0 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
1a4c0 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
1a4d0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
1a4e0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
1a4f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1a500 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
1a510 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
1a520 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
1a530 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  .<dd>.**.** <dt>
1a540 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1a550 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1a560 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1a570 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
1a580 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
1a590 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1a5a0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
1a5b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1a5c0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1a5d0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
1a5e0 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
1a5f0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
1a600 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
1a610 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
1a620 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
1a630 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
1a640 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
1a650 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
1a660 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a  BY clause.</dd>.
1a670 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1a680 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
1a690 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1a6a0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
1a6b0 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
1a6c0 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
1a6d0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
1a6e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1a6f0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
1a700 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1a710 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1a720 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
1a730 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
1a740 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a  atement.</dd>.**
1a750 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1a760 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
1a770 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1a780 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
1a790 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
1a7a0 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
1a7b0 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
1a7c0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
1a7d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c   SQL statement.<
1a7e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1a7f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
1a800 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
1a810 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1a820 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
1a830 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
1a840 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
1a850 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1a860 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
1a870 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1a880 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
1a890 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
1a8a0 74 61 62 61 73 65 73 5d 2e 3c 2f 64 64 3e 0a 2a  tabases].</dd>.*
1a8b0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1a8c0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
1a8d0 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
1a8e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1a8f0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
1a900 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
1a910 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
1a920 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
1a930 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ators.</dd>.**.*
1a940 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1a950 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1a960 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
1a970 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1a980 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69  r of variables i
1a990 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1a9a0 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62  nt that can.** b
1a9b0 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a  e bound.</dd>.**
1a9c0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1a9d0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
1a9e0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1a9f0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
1aa00 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
1aa10 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
1aa20 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
1aa30 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1aa40 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
1aa50 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
1aa60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1aa70 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
1aa80 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
1aa90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1aaa0 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
1aab0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
1aac0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1aad0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
1aae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
1aaf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ab00 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
1ab10 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1ab20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
1ab30 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
1ab40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ab50 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
1ab60 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1ab70 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
1ab80 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
1ab90 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1aba0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1abb0 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
1abc0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1abd0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
1abe0 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
1abf0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1ac00 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
1ac10 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
1ac20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
1ac30 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  GER_DEPTH       
1ac40 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43       10../*.** C
1ac50 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
1ac60 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
1ac70 65 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c 53 31  ent {H13010} <S1
1ac80 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0000>.** KEYWORD
1ac90 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e  S: {SQL statemen
1aca0 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a  t compiler}.**.*
1acb0 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20  * To execute an 
1acc0 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75  SQL query, it mu
1acd0 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
1ace0 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
1acf0 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
1ad00 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
1ad10 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
1ad20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
1ad30 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73  gument, "db", is
1ad40 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1ad50 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65  nection] obtaine
1ad60 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f  d from a.** prio
1ad70 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
1ad80 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
1ad90 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1ada0 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  open_v2()] or.**
1adb0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1adc0 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61  ()].  The databa
1add0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
1ade0 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e  st not have been
1adf0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
1ae00 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1ae10 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
1ae20 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
1ae30 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
1ae40 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
1ae50 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1ae60 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
1ae70 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
1ae80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1ae90 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
1aea0 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
1aeb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1aec0 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
1aed0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
1aee0 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  * use UTF-16..**
1aef0 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65  .** If the nByte
1af00 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
1af10 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
1af20 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
1af30 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
1af40 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
1af50 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e  r. If nByte is n
1af60 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1af70 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
1af80 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
1af90 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
1afa0 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42  m zSql.  When nB
1afb0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
1afc0 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
1afd0 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
1afe0 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
1aff0 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
1b000 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
1b010 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68  .** the nByte-th
1b020 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
1b030 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66   comes first. If
1b040 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
1b050 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75  s.** that the su
1b060 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
1b070 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
1b080 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61   then there is a
1b090 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72   small.** perfor
1b0a0 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
1b0b0 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20  to be gained by 
1b0c0 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
1b0d0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
1b0e0 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
1b0f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1b100 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
1b110 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
1b120 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
1b130 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
1b140 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 70 7a  tes..**.** If pz
1b150 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
1b160 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
1b170 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
1b180 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
1b190 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
1b1a0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
1b1b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
1b1c0 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
1b1d0 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
1b1e0 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
1b1f0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
1b200 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
1b210 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
1b220 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
1b230 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
1b240 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  ** *ppStmt is le
1b250 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
1b260 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
1b270 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1b280 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
1b290 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
1b2a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
1b2b0 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
1b2c0 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
1b2d0 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
1b2e0 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20 74    If the input t
1b2f0 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
1b300 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
1b310 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
1b320 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
1b330 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
1b340 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
1b350 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
1b360 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
1b370 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
1b380 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
1b390 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
1b3a0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1b3b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1b3c0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
1b3d0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
1b3e0 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
1b3f0 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
1b400 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51   On success, [SQ
1b410 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1b420 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 65 20  rned, otherwise 
1b430 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1b440 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1b450 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
1b460 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
1b470 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1b480 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
1b490 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
1b4a0 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
1b4b0 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
1b4c0 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
1b4d0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
1b4e0 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
1b4f0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
1b500 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
1b510 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
1b520 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e  * In the "v2" in
1b530 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
1b540 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1b550 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
1b560 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
1b570 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
1b580 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
1b590 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
1b5a0 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
1b5b0 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
1b5c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
1b5d0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
1b5e0 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e  ehave a differen
1b5f0 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
1b600 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
1b610 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20   <li>.** If the 
1b620 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
1b630 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
1b640 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
1b650 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
1b660 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
1b670 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
1b680 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1b690 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
1b6a0 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
1b6b0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
1b6c0 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
1b6d0 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63  gain.  If the sc
1b6e0 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64  hema has changed
1b6f0 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61   in.** a way tha
1b700 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74  t makes the stat
1b710 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20  ement no longer 
1b720 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f  valid, [sqlite3_
1b730 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69  step()] will sti
1b740 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
1b750 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42  LITE_SCHEMA].  B
1b760 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65  ut unlike the le
1b770 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b  gacy behavior, [
1b780 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69  SQLITE_SCHEMA] i
1b790 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c  s.** now a fatal
1b7a0 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67   error.  Calling
1b7b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1b7c0 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69  e_v2()] again wi
1b7d0 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a  ll not make the.
1b7e0 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79  ** error go away
1b7f0 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71  .  Note: use [sq
1b800 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
1b810 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74  to find the text
1b820 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69  .** of the parsi
1b830 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72 65  ng error that re
1b840 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c  sults in an [SQL
1b850 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75  ITE_SCHEMA] retu
1b860 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  rn..** </li>.**.
1b870 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20  ** <li>.** When 
1b880 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
1b890 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1b8a0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
1b8b0 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
1b8c0 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
1b8d0 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
1b8e0 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54  error codes].  T
1b8f0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1b900 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
1b910 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1b920 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
1b930 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
1b940 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
1b950 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f  t code.** and yo
1b960 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  u would have to 
1b970 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
1b980 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
1b990 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72  eset()] in order
1b9a0 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20  .** to find the 
1b9b0 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
1b9c0 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
1b9d0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
1b9e0 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
1b9f0 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
1ba00 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
1ba10 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
1ba20 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1ba30 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
1ba40 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
1ba50 65 20 76 61 6c 75 65 20 6f 66 20 61 20 5b 70 61  e value of a [pa
1ba60 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
1ba70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
1ba80 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
1ba90 67 68 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  ght.** change th
1baa0 65 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  e query plan for
1bab0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1bac0 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
1bad0 20 6d 61 79 20 62 65 0a 2a 2a 20 61 75 74 6f 6d   may be.** autom
1bae0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
1baf0 6c 65 64 20 28 61 73 20 69 66 20 74 68 65 72 65  led (as if there
1bb00 20 68 61 64 20 62 65 65 6e 20 61 20 73 63 68 65   had been a sche
1bb10 6d 61 20 63 68 61 6e 67 65 29 20 6f 6e 20 74 68  ma change) on th
1bb20 65 20 66 69 72 73 74 20 0a 2a 2a 20 5b 73 71 6c  e first .** [sql
1bb30 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
1bb40 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
1bb50 63 68 61 6e 67 65 20 74 6f 20 74 68 65 20 0a 2a  change to the .*
1bb60 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1bb70 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
1bb80 20 6f 66 20 74 68 65 20 5b 70 61 72 61 6d 65 74   of the [paramet
1bb90 65 72 5d 2e 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  er]. .** </li>.*
1bba0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
1bbb0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
1bbc0 48 31 33 30 31 31 5d 20 5b 48 31 33 30 31 32 5d  H13011] [H13012]
1bbd0 20 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 30 31   [H13013] [H1301
1bbe0 34 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 31 33  4] [H13015] [H13
1bbf0 30 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 5b 48  016] [H13019] [H
1bc00 31 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74  13021].**.*/.int
1bc10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1bc20 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1bc30 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1bc40 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1bc50 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1bc60 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1bc70 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1bc80 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1bc90 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1bca0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1bcb0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1bcc0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1bcd0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1bce0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1bcf0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1bd00 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1bd10 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1bd20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1bd30 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1bd40 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1bd50 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1bd60 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
1bd70 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1bd80 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1bd90 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1bda0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1bdb0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1bdc0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1bdd0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1bde0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1bdf0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1be00 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1be10 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1be20 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1be30 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1be40 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1be50 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1be60 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1be70 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1be80 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1be90 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1bea0 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
1beb0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1bec0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1bed0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1bee0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
1bef0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1bf00 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
1bf10 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1bf20 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1bf30 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1bf40 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1bf50 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1bf60 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1bf70 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1bf80 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1bf90 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1bfa0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1bfb0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1bfc0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1bfd0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1bfe0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1bff0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
1c000 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1c010 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1c020 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1c030 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
1c040 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1c050 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
1c060 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1c070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1c080 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1c090 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1c0a0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1c0b0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1c0c0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1c0d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1c0e0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
1c0f0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1c100 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1c110 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1c120 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1c130 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
1c140 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b   Statement SQL {
1c150 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e  H13100} <H13000>
1c160 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1c170 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1c180 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
1c190 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
1c1a0 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
1c1b0 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
1c1c0 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
1c1d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
1c1e0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
1c1f0 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
1c200 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
1c210 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1c220 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
1c230 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
1c240 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1c250 74 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 5d 20  ts:.** [H13101] 
1c260 5b 48 31 33 31 30 32 5d 20 5b 48 31 33 31 30 33  [H13102] [H13103
1c270 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ].*/.const char 
1c280 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
1c290 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
1c2a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c2b0 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
1c2c0 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
1c2d0 63 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30  ct {H15000} <S20
1c2e0 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
1c2f0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
1c300 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
1c310 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1c320 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
1c330 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
1c340 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1c350 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
1c360 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
1c370 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
1c380 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
1c390 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
1c3a0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
1c3b0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
1c3c0 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61  es it stores. Va
1c3d0 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
1c3e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1c3f0 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
1c400 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
1c410 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
1c420 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
1c430 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
1c440 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
1c450 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
1c460 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
1c470 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
1c480 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
1c490 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
1c4a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1c4b0 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
1c4c0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
1c4d0 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
1c4e0 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
1c4f0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
1c500 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
1c510 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
1c520 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
1c530 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
1c540 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
1c550 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
1c560 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
1c570 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1c580 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
1c590 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
1c5a0 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
1c5b0 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
1c5c0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
1c5d0 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
1c5e0 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d  d.  A internal m
1c5f0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
1c600 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
1c610 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1c620 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
1c630 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
1c640 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1c650 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1c660 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
1c670 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
1c680 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
1c690 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
1c6a0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
1c6b0 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
1c6c0 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
1c6d0 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
1c6e0 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
1c6f0 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
1c700 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
1c710 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
1c720 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
1c730 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
1c740 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
1c750 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
1c760 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
1c770 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
1c780 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
1c790 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1c7a0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
1c7b0 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
1c7c0 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
1c7d0 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
1c7e0 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
1c7f0 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
1c800 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
1c810 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
1c820 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
1c830 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
1c840 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e   between between
1c850 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
1c860 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
1c870 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1c880 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
1c890 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
1c8a0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
1c8b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1c8c0 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
1c8d0 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
1c8e0 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
1c8f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1c900 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
1c910 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
1c920 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
1c930 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
1c940 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1c950 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
1c960 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
1c970 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
1c980 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
1c990 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1c9a0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
1c9b0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
1c9c0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
1c9d0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
1c9e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
1c9f0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
1ca00 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
1ca10 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
1ca20 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
1ca30 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
1ca40 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
1ca50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1ca60 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
1ca70 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1ca80 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
1ca90 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
1caa0 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
1cab0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
1cac0 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30   {H16001} <S2020
1cad0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  0>.**.** The con
1cae0 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
1caf0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
1cb00 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
1cb10 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
1cb20 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
1cb30 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  .  A pointer to 
1cb40 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
1cb50 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
1cb60 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
1cb70 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
1cb80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
1cb90 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
1cba0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1cbb0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
1cbc0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
1cbd0 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
1cbe0 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
1cbf0 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
1cc00 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
1cc10 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
1cc20 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
1cc30 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
1cc40 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
1cc50 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
1cc60 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
1cc70 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
1cc80 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
1cc90 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
1cca0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
1ccb0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
1ccc0 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
1ccd0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1cce0 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
1ccf0 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
1cd00 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
1cd10 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
1cd20 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20  ared Statements 
1cd30 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30  {H13500} <S70300
1cd40 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
1cd50 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
1cd60 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
1cd70 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
1cd80 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
1cd90 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
1cda0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
1cdb0 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
1cdc0 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
1cdd0 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e  In the SQL strin
1cde0 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  gs input to [sql
1cdf0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ce00 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
1ce10 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
1ce20 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
1ce30 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
1ce40 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f  ] that matches o
1ce50 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ne of following.
1ce60 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a  ** templates:.**
1ce70 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
1ce80 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
1ce90 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
1cea0 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
1ceb0 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
1cec0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
1ced0 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76  e templates abov
1cee0 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74  e, NNN represent
1cef0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
1cf00 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
1cf10 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61   represents an a
1cf20 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e  lphanumeric iden
1cf30 74 69 66 65 72 2e 20 20 54 68 65 20 76 61 6c 75  tifer.  The valu
1cf40 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
1cf50 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
1cf60 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
1cf70 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
1cf80 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
1cf90 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
1cfa0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
1cfb0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1cfc0 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
1cfd0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
1cfe0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1cff0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1d000 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
1d010 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
1d020 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
1d030 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
1d040 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
1d050 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1d060 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
1d070 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
1d080 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1d090 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
1d0a0 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
1d0b0 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
1d0c0 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73 74  .** The leftmost
1d0d0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
1d0e0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
1d0f0 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65  .  When the same
1d100 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
1d110 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
1d120 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
1d130 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
1d140 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
1d150 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
1d160 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
1d170 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
1d180 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20 66  ..** The index f
1d190 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
1d1a0 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
1d1b0 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
1d1c0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1d1d0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1d1e0 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
1d1f0 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a  d.  The index.**
1d200 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
1d210 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
1d220 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54  lue of NNN..** T
1d230 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
1d240 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
1d250 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
1d260 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
1d270 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
1d280 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
1d290 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
1d2a0 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
1d2b0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
1d2c0 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
1d2d0 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
1d2e0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1d2f0 20 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e   In those routin
1d300 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
1d310 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
1d320 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
1d330 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
1d340 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
1d350 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
1d360 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
1d370 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
1d380 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
1d390 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
1d3a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1d3b0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66  haracters..** If
1d3c0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
1d3d0 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
1d3e0 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  e, the length of
1d3f0 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
1d400 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
1d410 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
1d420 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
1d430 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  nator..**.** The
1d440 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
1d450 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
1d460 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
1d470 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
1d480 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
1d490 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
1d4a0 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
1d4b0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
1d4c0 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
1d4d0 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
1d4e0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1d4f0 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 69 66  h it. If the fif
1d500 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
1d510 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
1d520 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
1d530 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
1d540 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
1d550 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
1d560 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
1d570 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
1d580 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
1d590 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
1d5a0 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72   If the fifth ar
1d5b0 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
1d5c0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
1d5d0 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
1d5e0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
1d5f0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
1d600 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
1d610 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
1d620 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
1d630 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
1d640 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
1d650 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * The sqlite3_bi
1d660 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
1d670 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
1d680 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
1d690 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
1d6a0 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 41   with zeroes.  A
1d6b0 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
1d6c0 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
1d6d0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
1d6e0 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
1d6f0 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
1d700 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
1d710 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
1d720 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
1d730 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
1d740 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
1d750 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
1d760 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
1d770 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
1d780 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
1d790 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
1d7a0 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
1d7b0 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67  utines..** A neg
1d7c0 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
1d7d0 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
1d7e0 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
1d7f0 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
1d800 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * The sqlite3_bi
1d810 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
1d820 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61  must be called a
1d830 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fter.** [sqlite3
1d840 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28  _prepare_v2()] (
1d850 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
1d860 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ) or [sqlite3_re
1d870 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65  set()] and.** be
1d880 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  fore [sqlite3_st
1d890 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e  ep()]..** Bindin
1d8a0 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
1d8b0 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
1d8c0 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
1d8d0 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20  ine..** Unbound 
1d8e0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
1d8f0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
1d900 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  LL..**.** These 
1d910 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1d920 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
1d930 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72  uccess or an err
1d940 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e  or code if.** an
1d950 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
1d960 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47  g.  [SQLITE_RANG
1d970 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
1d980 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
1d990 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
1d9a0 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49  of range.  [SQLI
1d9b0 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
1d9c0 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
1d9d0 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c  ) fails..** [SQL
1d9e0 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68  ITE_MISUSE] migh
1d9f0 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66  t be returned if
1da00 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1da10 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a  are called on a.
1da20 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69  ** virtual machi
1da30 6e 65 20 74 68 61 74 20 69 73 20 74 68 65 20 77  ne that is the w
1da40 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68  rong state or wh
1da50 69 63 68 20 68 61 73 20 61 6c 72 65 61 64 79 20  ich has already 
1da60 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a  been finalized..
1da70 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20  ** Detection of 
1da80 6d 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69  misuse is unreli
1da90 61 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69  able.  Applicati
1daa0 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64  ons should not d
1dab0 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49  epend.** on SQLI
1dac0 54 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e  TE_MISUSE return
1dad0 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  s.  SQLITE_MISUS
1dae0 45 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  E is intended to
1daf0 20 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61   indicate a.** a
1db00 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
1db10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
1db20 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1db30 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
1db40 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65  t.** panic rathe
1db50 72 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51  r than return SQ
1db60 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a  LITE_MISUSE..**.
1db70 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1db80 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1db90 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
1dba0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1dbb0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
1dbc0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1dbd0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1dbe0 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52  ndex()]..**.** R
1dbf0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1dc00 5b 48 31 33 35 30 36 5d 20 5b 48 31 33 35 30 39  [H13506] [H13509
1dc10 5d 20 5b 48 31 33 35 31 32 5d 20 5b 48 31 33 35  ] [H13512] [H135
1dc20 31 35 5d 20 5b 48 31 33 35 31 38 5d 20 5b 48 31  15] [H13518] [H1
1dc30 33 35 32 31 5d 20 5b 48 31 33 35 32 34 5d 20 5b  3521] [H13524] [
1dc40 48 31 33 35 32 37 5d 0a 2a 2a 20 5b 48 31 33 35  H13527].** [H135
1dc50 33 30 5d 20 5b 48 31 33 35 33 33 5d 20 5b 48 31  30] [H13533] [H1
1dc60 33 35 33 36 5d 20 5b 48 31 33 35 33 39 5d 20 5b  3536] [H13539] [
1dc70 48 31 33 35 34 32 5d 20 5b 48 31 33 35 34 35 5d  H13542] [H13545]
1dc80 20 5b 48 31 33 35 34 38 5d 20 5b 48 31 33 35 35   [H13548] [H1355
1dc90 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c  1].**.*/.int sql
1dca0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
1dcb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1dcc0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
1dcd0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
1dce0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
1dcf0 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
1dd00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1dd10 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
1dd20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
1dd30 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
1dd40 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
1dd50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
1dd60 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
1dd70 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
1dd80 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
1dd90 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
1dda0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
1ddb0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1ddc0 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
1ddd0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
1dde0 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20  t char*, int n, 
1ddf0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
1de00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1de10 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
1de20 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1de30 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
1de40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1de50 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1de60 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
1de70 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
1de80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
1de90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1dea0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
1deb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1dec0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
1ded0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
1dee0 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
1def0 73 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 30 33  s {H13600} <S703
1df00 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
1df10 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
1df20 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
1df30 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
1df40 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
1df50 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1df60 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
1df70 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
1df80 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
1df90 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
1dfa0 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
1dfb0 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
1dfc0 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
1dfd0 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
1dfe0 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
1dff0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
1e000 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
1e010 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
1e020 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
1e030 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1e040 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
1e050 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
1e060 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
1e070 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
1e080 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
1e090 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
1e0a0 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
1e0b0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
1e0c0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
1e0d0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
1e0e0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1e0f0 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a   ?NNN are used,.
1e100 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
1e110 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
1e120 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1e130 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1e140 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
1e150 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
1e160 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1e170 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
1e180 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1e190 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1e1a0 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
1e1b0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 30  ments:.** [H1360
1e1c0 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  1].*/.int sqlite
1e1d0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1e1e0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
1e1f0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
1e200 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
1e210 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
1e220 20 7b 48 31 33 36 32 30 7d 20 3c 53 37 30 33 30   {H13620} <S7030
1e230 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
1e240 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
1e250 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e  pointer to the n
1e260 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a  ame of the n-th.
1e270 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  ** [SQL paramete
1e280 72 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  r] in a [prepare
1e290 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
1e2a0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
1e2b0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
1e2c0 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
1e2d0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
1e2e0 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
1e2f0 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
1e300 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
1e310 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
1e320 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
1e330 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
1e340 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
1e350 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
1e360 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
1e370 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
1e380 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
1e390 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74  name..** Paramet
1e3a0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
1e3b0 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
1e3c0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
1e3d0 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
1e3e0 61 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65 66  and are also ref
1e3f0 65 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e 6f  erred to as "ano
1e400 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
1e410 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  s"..**.** The fi
1e420 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
1e430 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
1e440 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
1e450 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  ** If the value 
1e460 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  n is out of rang
1e470 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68  e or if the n-th
1e480 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1e490 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
1e4a0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
1e4b0 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  .  The returned 
1e4c0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
1e4d0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
1e4e0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
1e4f0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
1e500 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
1e510 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
1e520 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
1e530 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1e540 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1e550 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1e560 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1e570 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1e580 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
1e590 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1e5a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1e5b0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
1e5c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1e5d0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1e5e0 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
1e5f0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 32  ments:.** [H1362
1e600 31 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  1].*/.const char
1e610 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
1e620 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
1e630 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1e640 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e650 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
1e660 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
1e670 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36  Given Name {H136
1e680 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  40} <S70300>.**.
1e690 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e  ** Return the in
1e6a0 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
1e6b0 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
1e6c0 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20  s name.  The.** 
1e6d0 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
1e6e0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
1e6f0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
1e700 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
1e710 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1e720 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1e730 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65  3_bind()].  A ze
1e740 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
1e750 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
1e760 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
1e770 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65  und.  The parame
1e780 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
1e790 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
1e7a0 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
1e7b0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1e7c0 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
1e7d0 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
1e7e0 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
1e7f0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1e800 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
1e810 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
1e820 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1e830 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
1e840 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1e850 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
1e860 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1e870 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1e880 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ()]..**.** Requi
1e890 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1e8a0 36 34 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  641].*/.int sqli
1e8b0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1e8c0 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
1e8d0 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
1e8e0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
1e8f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
1e900 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
1e910 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
1e920 61 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d  atement {H13660}
1e930 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70300>.**.** 
1e940 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
1e950 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
1e960 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
1e970 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
1e980 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
1e990 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
1e9a0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
1e9b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e9c0 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73  nt]..** Use this
1e9d0 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
1e9e0 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
1e9f0 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
1ea00 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1ea10 73 3a 0a 2a 2a 20 5b 48 31 33 36 36 31 5d 0a 2a  s:.** [H13661].*
1ea20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
1ea30 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
1ea40 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
1ea50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
1ea60 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
1ea70 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20  In A Result Set 
1ea80 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30 30  {H13710} <S10700
1ea90 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  >.**.** Return t
1eaa0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
1eab0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
1eac0 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
1ead0 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
1eae0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
1eaf0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
1eb00 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
1eb10 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
1eb20 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
1eb30 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
1eb40 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
1eb50 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a   [UPDATE])..**.*
1eb60 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
1eb70 2a 2a 20 5b 48 31 33 37 31 31 5d 0a 2a 2f 0a 69  ** [H13711].*/.i
1eb80 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
1eb90 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
1eba0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1ebb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1ebc0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
1ebd0 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33   Result Set {H13
1ebe0 37 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  720} <S10700>.**
1ebf0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1ec00 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
1ec10 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
1ec20 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
1ec30 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
1ec40 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
1ec50 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
1ec60 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f    The sqlite3_co
1ec70 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
1ec80 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1ec90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1eca0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1ecb0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
1ecc0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
1ecd0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
1ece0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1ecf0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1ed00 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1ed10 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74 20  ing.  The first 
1ed20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
1ed30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1ed40 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
1ed50 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
1ed60 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
1ed70 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
1ed80 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1ed90 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
1eda0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
1edb0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
1edc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  .**.** The retur
1edd0 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
1ede0 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
1edf0 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
1ee00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1ee10 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
1ee20 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
1ee30 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
1ee40 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
1ee50 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
1ee60 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
1ee70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1ee80 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
1ee90 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
1eea0 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * If sqlite3_mal
1eeb0 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
1eec0 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
1eed0 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
1eee0 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
1eef0 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
1ef00 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
1ef10 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
1ef20 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
1ef30 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
1ef40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ..**.** The name
1ef50 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
1ef60 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
1ef70 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
1ef80 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
1ef90 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
1efa0 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
1efb0 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
1efc0 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
1efd0 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
1efe0 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
1eff0 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
1f000 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
1f010 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
1f020 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
1f030 78 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  xt..**.** Requir
1f040 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37  ements:.** [H137
1f050 32 31 5d 20 5b 48 31 33 37 32 33 5d 20 5b 48 31  21] [H13723] [H1
1f060 33 37 32 34 5d 20 5b 48 31 33 37 32 35 5d 20 5b  3724] [H13725] [
1f070 48 31 33 37 32 36 5d 20 5b 48 31 33 37 32 37 5d  H13726] [H13727]
1f080 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1f090 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1f0a0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1f0b0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
1f0c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
1f0d0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
1f0e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
1f0f0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
1f100 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
1f110 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
1f120 65 73 75 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c  esult {H13740} <
1f130 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10700>.**.** Th
1f140 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
1f150 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
1f160 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63  determine what c
1f170 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a  olumn of what.**
1f180 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20   table in which 
1f190 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c  database a resul
1f1a0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
1f1b0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20  statement comes 
1f1c0 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d  from..** The nam
1f1d0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
1f1e0 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
1f1f0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
1f200 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
1f210 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
1f220 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65  -16 string.  The
1f230 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
1f240 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
1f250 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
1f260 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
1f270 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
1f280 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
1f290 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
1f2a0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1f2b0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
1f2c0 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65  ..** The returne
1f2d0 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
1f2e0 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
1f2f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f300 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
1f310 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1f320 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
1f330 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
1f340 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
1f350 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
1f360 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
1f370 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  ncoding..**.** T
1f380 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
1f390 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
1f3a0 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
1f3b0 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
1f3c0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
1f3d0 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
1f3e0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
1f3f0 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f  ent to the follo
1f400 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20  wing calls is a 
1f410 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f420 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66  ent]..** These f
1f430 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
1f440 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
1f450 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  t the Nth column
1f460 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1f470 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
1f480 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
1f490 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
1f4a0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  gument..**.** If
1f4b0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1f4c0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
1f4d0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
1f4e0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
1f4f0 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
1f500 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
1f510 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
1f520 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
1f530 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
1f540 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20    These routine 
1f550 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
1f560 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
1f570 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
1f580 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
1f590 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
1f5a0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
1f5b0 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
1f5c0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 0a  database, table.
1f5d0 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68  ** and column th
1f5e0 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
1f5f0 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
1f600 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
1f610 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68   As with all oth
1f620 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
1f630 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20  those postfixed 
1f640 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
1f650 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
1f660 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20  ed strings, the 
1f670 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
1f680 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45  return UTF-8. {E
1f690 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ND}.**.** These 
1f6a0 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
1f6b0 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
1f6c0 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
1f6d0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
1f6e0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
1f6f0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
1f700 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
1f710 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
1f720 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a  *.** {A13751}.**
1f730 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
1f740 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
1f750 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
1f760 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
1f770 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
1f780 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f790 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
1f7a0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
1f7b0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
1f7c0 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
1f7d0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
1f7e0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 34 31 5d  nts:.** [H13741]
1f7f0 20 5b 48 31 33 37 34 32 5d 20 5b 48 31 33 37 34   [H13742] [H1374
1f800 33 5d 20 5b 48 31 33 37 34 34 5d 20 5b 48 31 33  3] [H13744] [H13
1f810 37 34 35 5d 20 5b 48 31 33 37 34 36 5d 20 5b 48  745] [H13746] [H
1f820 31 33 37 34 38 5d 0a 2a 2a 0a 2a 2a 20 49 66 20  13748].**.** If 
1f830 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
1f840 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
1f850 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
1f860 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
1f870 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
1f880 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
1f890 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
1f8a0 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
1f8b0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
1f8c0 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
1f8d0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
1f8e0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
1f8f0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
1f900 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1f910 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
1f920 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
1f930 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1f940 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1f950 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
1f960 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
1f970 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
1f980 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1f990 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
1f9a0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1f9b0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
1f9c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
1f9d0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
1f9e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1f9f0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
1fa00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
1fa10 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
1fa20 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1fa30 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1fa40 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
1fa50 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
1fa60 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
1fa70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
1fa80 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
1fa90 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
1faa0 20 7b 48 31 33 37 36 30 7d 20 3c 53 31 30 37 30   {H13760} <S1070
1fab0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  0>.**.** The fir
1fac0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
1fad0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1fae0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
1faf0 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
1fb00 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
1fb10 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
1fb20 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
1fb30 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
1fb40 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
1fb50 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
1fb60 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
1fb70 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
1fb80 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
1fb90 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
1fba0 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
1fbb0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
1fbc0 75 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e  urned.  If the N
1fbd0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
1fbe0 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
1fbf0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
1fc00 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
1fc10 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
1fc20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1fc30 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
1fc40 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
1fc50 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45  TF-8 encoded. {E
1fc60 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ND}.**.** For ex
1fc70 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
1fc80 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
1fc90 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
1fca0 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
1fcb0 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
1fcc0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
1fcd0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
1fce0 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
1fcf0 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
1fd00 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
1fd10 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
1fd20 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
1fd30 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
1fd40 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
1fd50 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
1fd60 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
1fd70 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
1fd80 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
1fd90 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a  umn (i==0)..**.*
1fda0 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  * SQLite uses dy
1fdb0 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
1fdc0 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20  yping.  So just 
1fdd0 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
1fde0 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
1fdf0 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
1fe00 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
1fe10 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
1fe20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
1fe30 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
1fe40 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
1fe50 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
1fe60 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
1fe70 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
1fe80 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
1fe90 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
1fea0 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
1feb0 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
1fec0 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
1fed0 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
1fee0 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
1fef0 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
1ff00 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  es..**.** Requir
1ff10 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37  ements:.** [H137
1ff20 36 31 5d 20 5b 48 31 33 37 36 32 5d 20 5b 48 31  61] [H13762] [H1
1ff30 33 37 36 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63  3763].*/.const c
1ff40 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
1ff50 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
1ff60 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
1ff70 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
1ff80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
1ff90 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
1ffa0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
1ffb0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
1ffc0 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
1ffd0 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c  ement {H13200} <
1ffe0 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66  S10000>.**.** Af
1fff0 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
20000 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
20010 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
20020 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
20030 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20040 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
20050 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
20060 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
20070 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
20080 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
20090 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
200a0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
200b0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
200c0 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
200d0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
200e0 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
200f0 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
20100 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
20110 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
20120 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
20130 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
20140 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
20150 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
20160 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
20170 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
20180 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
20190 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
201a0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
201b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
201c0 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
201d0 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
201e0 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
201f0 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
20200 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20210 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
20220 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
20230 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
20240 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
20250 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
20260 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
20270 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
20280 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
20290 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
202a0 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
202b0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
202c0 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
202d0 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
202e0 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
202f0 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
20300 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
20310 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
20320 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
20330 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
20340 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
20350 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
20360 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
20370 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
20380 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
20390 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
203a0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
203b0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
203c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
203d0 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
203e0 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
203f0 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
20400 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
20410 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65  its job.  If the
20420 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
20430 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
20440 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
20450 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
20460 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
20470 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
20480 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
20490 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
204a0 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
204b0 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
204c0 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63  thin a.** explic
204d0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
204e0 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
204f0 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
20500 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
20510 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
20520 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
20530 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
20540 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
20550 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
20560 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
20570 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
20580 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
20590 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
205a0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
205b0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
205c0 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
205d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
205e0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
205f0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
20600 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
20610 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
20620 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
20630 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
20640 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
20650 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
20660 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
20670 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
20680 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
20690 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
206a0 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
206b0 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
206c0 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
206d0 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
206e0 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
206f0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
20700 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
20710 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
20720 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
20730 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
20740 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  a..**.** [SQLITE
20750 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
20760 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
20770 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
20780 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
20790 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
207a0 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
207b0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
207c0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
207d0 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
207e0 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
207f0 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
20800 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
20810 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57  _errmsg()]..** W
20820 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
20830 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
20840 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
20850 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
20860 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
20870 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
20880 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
20890 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
208a0 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
208b0 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
208c0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
208d0 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
208e0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
208f0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74  tatement].  In t
20900 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
20910 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
20920 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
20930 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
20940 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
20950 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
20960 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
20970 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
20980 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
20990 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
209a0 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
209b0 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
209c0 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
209d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
209e0 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
209f0 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
20a00 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
20a10 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
20a20 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
20a30 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
20a40 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
20a50 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
20a60 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
20a70 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
20a80 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
20a90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
20aa0 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
20ab0 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
20ac0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
20ad0 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
20ae0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
20af0 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
20b00 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
20b10 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
20b20 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
20b30 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
20b40 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
20b50 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
20b60 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
20b70 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
20b80 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
20b90 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
20ba0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
20bb0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
20bc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
20bd0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
20be0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
20bf0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
20c00 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
20c10 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
20c20 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
20c30 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
20c40 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
20c50 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
20c60 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
20c70 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
20c80 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
20c90 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
20ca0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
20cb0 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
20cc0 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
20cd0 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
20ce0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20cf0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
20d00 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
20d10 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
20d20 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
20d30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
20d40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
20d50 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
20d60 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
20d70 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
20d80 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
20d90 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
20da0 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
20db0 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
20dc0 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
20dd0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
20de0 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommended..**.** 
20df0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
20e00 20 5b 48 31 33 32 30 32 5d 20 5b 48 31 35 33 30   [H13202] [H1530
20e10 34 5d 20 5b 48 31 35 33 30 36 5d 20 5b 48 31 35  4] [H15306] [H15
20e20 33 30 38 5d 20 5b 48 31 35 33 31 30 5d 0a 2a 2f  308] [H15310].*/
20e30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
20e40 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
20e50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20e60 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
20e70 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
20e80 20 73 65 74 20 7b 48 31 33 37 37 30 7d 20 3c 53   set {H13770} <S
20e90 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74  10700>.**.** Ret
20ea0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
20eb0 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65  of values in the
20ec0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
20ed0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a  the result set..
20ee0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
20ef0 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 37 31 5d 20  ts:.** [H13771] 
20f00 5b 48 31 33 37 37 32 5d 0a 2a 2f 0a 69 6e 74 20  [H13772].*/.int 
20f10 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
20f20 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
20f30 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
20f40 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
20f50 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 20  ental Datatypes 
20f60 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31 30  {H10265} <S10110
20f70 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59  ><S10120>.** KEY
20f80 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
20f90 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36  XT.**.** {H10266
20fa0 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  } Every value in
20fb0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
20fc0 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
20fd0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
20fe0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
20ff0 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
21000 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
21010 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
21020 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
21030 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
21040 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
21050 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
21060 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ul> {END}.**.** 
21070 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
21080 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
21090 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
210a0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
210b0 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
210c0 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
210d0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
210e0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
210f0 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
21100 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
21110 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
21120 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
21130 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
21140 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
21150 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
21160 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
21170 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
21180 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
21190 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
211a0 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
211b0 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
211c0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
211d0 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
211e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
211f0 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
21200 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
21210 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
21220 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
21230 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
21240 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
21250 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
21260 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
21270 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
21280 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 48   From A Query {H
21290 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a  13800} <S10700>.
212a0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
212b0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
212c0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
212d0 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
212e0 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
212f0 20 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63   query" interfac
21300 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
21310 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
21320 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
21330 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
21340 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
21350 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
21360 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76   a query.  In ev
21370 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
21380 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
21390 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
213a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
213b0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
213c0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
213d0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
213e0 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
213f0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
21400 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21410 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
21420 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
21430 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
21440 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
21450 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
21460 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
21470 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
21480 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
21490 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63    The leftmost c
214a0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
214b0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
214c0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 54 68 65 20  index 0..** The 
214d0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
214e0 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
214f0 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
21500 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
21510 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
21520 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
21530 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
21540 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
21550 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
21560 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
21570 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
21580 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
21590 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
215a0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
215b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
215c0 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
215d0 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
215e0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
215f0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
21600 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
21610 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
21620 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
21630 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
21640 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
21650 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
21660 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
21670 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
21680 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
21690 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
216a0 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
216b0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
216c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
216d0 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
216e0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
216f0 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
21700 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
21710 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
21720 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
21730 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
21740 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
21750 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
21760 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
21770 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
21780 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
21790 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
217a0 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
217b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
217c0 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
217d0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
217e0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
217f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
21800 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
21810 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
21820 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
21830 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
21840 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
21850 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
21860 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
21870 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65   column.  The re
21880 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
21890 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
218a0 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
218b0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
218c0 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
218d0 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
218e0 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
218f0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
21900 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
21910 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
21920 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
21930 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
21940 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
21950 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
21960 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
21970 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
21980 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
21990 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
219a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
219b0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
219c0 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
219d0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
219e0 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
219f0 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
21a00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
21a10 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
21a20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
21a30 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  .**.** If the re
21a40 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
21a50 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
21a60 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
21a70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
21a80 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
21a90 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
21aa0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
21ab0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
21ac0 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
21ad0 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
21ae0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
21af0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
21b00 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
21b10 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
21b20 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
21b30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
21b40 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72  tes..** If the r
21b50 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
21b60 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
21b70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
21b80 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
21b90 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
21ba0 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
21bb0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
21bc0 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
21bd0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
21be0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
21bf0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
21c00 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
21c10 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
21c20 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
21c30 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65  minator at the e
21c40 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
21c50 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74  ing.  For clarit
21c60 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  y: the value ret
21c70 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d  urned is the num
21c80 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
21c90 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
21ca0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
21cb0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
21cc0 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72  ** Strings retur
21cd0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
21ce0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
21cf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21d00 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
21d10 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
21d20 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
21d30 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68   terminated.  Th
21d40 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
21d50 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
21d60 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
21d70 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
21d80 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 72  LOB is an arbitr
21d90 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20  ary.** pointer, 
21da0 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20  possibly even a 
21db0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
21dc0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
21dd0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
21de0 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
21df0 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lar to sqlite3_c
21e00 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
21e10 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20   but leaves the 
21e20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36  result in UTF-16
21e30 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
21e40 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
21e50 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a   UTF-8..** The z
21e60 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
21e70 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69  s not included i
21e80 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a  n this count..**
21e90 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72  .** The object r
21ea0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
21eb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
21ec0 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
21ed0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
21ee0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
21ef0 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64    An unprotected
21f00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
21f10 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  bject.** may onl
21f20 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b  y be used with [
21f30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
21f40 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
21f50 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
21f60 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
21f70 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
21f80 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
21f90 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
21fa0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
21fb0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
21fc0 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
21fd0 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
21fe0 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
21ff0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
22000 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
22010 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
22020 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
22030 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
22040 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ()], then the be
22050 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
22060 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ned..**.** These
22070 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
22080 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
22090 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
220a0 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a  ropriate.  For.*
220b0 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
220c0 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
220d0 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
220e0 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
220f0 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
22100 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
22110 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
22120 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
22130 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
22140 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
22150 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66  atically.  The f
22160 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
22170 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
22180 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
22190 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
221a0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
221b0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
221c0 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
221d0 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
221e0 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
221f0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
22200 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
22210 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
22220 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
22230 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
22240 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
22250 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
22260 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
22270 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
22280 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
22290 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
222a0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
222b0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
222c0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
222d0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
222e0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
222f0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
22300 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
22310 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
22320 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
22330 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
22340 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
22350 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
22360 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
22370 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
22380 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
22390 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
223a0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
223b0 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
223c0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
223d0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
223e0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
223f0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f  Convert from flo
22400 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a  at to integer.**
22410 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
22420 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
22430 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
22440 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
22450 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
22460 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
22470 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
22480 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54  e as FLOAT->TEXT
22490 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
224a0 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
224b0 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  ER   <td> Use at
224c0 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
224d0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
224e0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73  FLOAT    <td> Us
224f0 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
22500 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
22510 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
22520 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
22530 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
22540 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
22550 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
22560 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
22570 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
22580 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
22590 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
225a0 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
225b0 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a  en use atof().**
225c0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
225d0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
225e0 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
225f0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
22600 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
22610 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
22620 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  te>.**.** The ta
22630 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
22640 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
22650 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
22660 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
22670 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
22680 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
22690 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
226a0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
226b0 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
226c0 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
226d0 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
226e0 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
226f0 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
22700 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
22710 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
22720 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
22730 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
22740 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
22750 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
22760 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
22770 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
22780 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
22790 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
227a0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
227b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
227c0 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
227d0 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
227e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
227f0 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
22800 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
22810 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
22820 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
22830 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
22840 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
22850 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
22860 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
22870 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
22880 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
22890 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
228a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
228b0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
228c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
228d0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
228e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
228f0 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
22900 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
22910 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
22920 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
22930 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
22940 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
22950 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
22960 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
22970 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
22980 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
22990 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
229a0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
229b0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
229c0 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
229d0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
229e0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
229f0 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
22a00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
22a10 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
22a20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22a30 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
22a40 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
22a50 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
22a60 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
22a70 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
22a80 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f  .**.** Conversio
22a90 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
22aa0 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
22ab0 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
22ac0 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
22ad0 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
22ae0 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
22af0 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
22b00 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
22b10 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
22b20 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
22b30 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20   pointer points 
22b40 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  to will have bee
22b50 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
22b60 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
22b70 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
22b80 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
22b90 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
22ba0 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
22bb0 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
22bc0 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
22bd0 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
22be0 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
22bf0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
22c00 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20   The safest and 
22c10 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
22c20 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
22c30 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
22c40 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
22c50 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
22c60 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
22c70 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
22c80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
22c90 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
22ca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
22cb0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
22cc0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
22cd0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
22ce0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
22cf0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
22d00 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
22d10 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
22d20 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
22d30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
22d40 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
22d50 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
22d60 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
22d70 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
22d80 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
22d90 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
22da0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
22db0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
22dc0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
22dd0 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
22de0 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
22df0 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
22e00 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
22e10 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
22e20 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
22e30 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
22e40 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
22e50 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
22e60 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
22e70 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
22e80 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
22e90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
22ea0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
22eb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
22ec0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
22ed0 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
22ee0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
22ef0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
22f00 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
22f10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
22f20 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tes()..**.** The
22f30 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
22f40 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
22f50 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
22f60 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
22f70 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
22f80 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
22f90 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
22fa0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
22fb0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
22fc0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
22fd0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d  called.  The mem
22fe0 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
22ff0 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
23000 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
23010 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
23020 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
23030 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
23040 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
23050 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
23060 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
23070 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
23080 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
23090 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
230a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d  ..**.** If a mem
230b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
230c0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
230d0 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
230e0 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
230f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
23100 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
23110 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
23120 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
23130 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
23140 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
23150 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
23160 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
23170 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
23180 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
23190 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
231a0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
231b0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
231c0 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65  NOMEM]..**.** Re
231d0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
231e0 48 31 33 38 30 33 5d 20 5b 48 31 33 38 30 36 5d  H13803] [H13806]
231f0 20 5b 48 31 33 38 30 39 5d 20 5b 48 31 33 38 31   [H13809] [H1381
23200 32 5d 20 5b 48 31 33 38 31 35 5d 20 5b 48 31 33  2] [H13815] [H13
23210 38 31 38 5d 20 5b 48 31 33 38 32 31 5d 20 5b 48  818] [H13821] [H
23220 31 33 38 32 34 5d 0a 2a 2a 20 5b 48 31 33 38 32  13824].** [H1382
23230 37 5d 20 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a 63  7] [H13830].*/.c
23240 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
23250 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
23260 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23270 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
23280 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
23290 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
232a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
232b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
232c0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
232d0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
232e0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
232f0 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
23300 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23310 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
23320 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
23330 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23340 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
23350 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
23360 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
23370 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
23380 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  Col);.const unsi
23390 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
233a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
233b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
233c0 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76  t iCol);.const v
233d0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
233e0 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
233f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
23400 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
23410 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
23420 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
23430 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76  iCol);.sqlite3_v
23440 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
23450 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
23460 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
23470 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
23480 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
23490 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
234a0 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 30  nt Object {H1330
234b0 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 31  0} <S70300><S301
234c0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
234d0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
234e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
234f0 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
23500 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23510 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ent]..** If the 
23520 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78  statement was ex
23530 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75  ecuted successfu
23540 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75  lly or not execu
23550 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e  ted at all, then
23560 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  .** SQLITE_OK is
23570 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20 65 78   returned. If ex
23580 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  ecution of the s
23590 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20  tatement failed 
235a0 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  then an.** [erro
235b0 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65  r code] or [exte
235c0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
235d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
235e0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
235f0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
23600 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
23610 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
23620 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   of the.** [prep
23630 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
23640 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61 6c    If the virtual
23650 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74   machine has not
23660 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
23670 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69  ecution when thi
23680 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  s routine is cal
23690 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b  led, that is lik
236a0 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e  e.** encounterin
236b0 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e  g an error or an
236c0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
236d0 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d  upt | interrupt]
236e0 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20  ..** Incomplete 
236f0 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72  updates may be r
23700 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74  olled back and t
23710 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63  ransactions canc
23720 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69  eled,.** dependi
23730 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d  ng on the circum
23740 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65  stances, and the
23750 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
23760 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62   returned will b
23770 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  e [SQLITE_ABORT]
23780 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
23790 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 33 30 32  ents:.** [H11302
237a0 5d 20 5b 48 31 31 33 30 34 5d 0a 2a 2f 0a 69 6e  ] [H11304].*/.in
237b0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
237c0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
237d0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
237e0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
237f0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
23800 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33  ment Object {H13
23810 33 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  330} <S70300>.**
23820 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
23830 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
23840 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
23850 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
23860 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
23870 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
23880 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
23890 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
238a0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  xecuted..** Any 
238b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
238c0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
238d0 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
238e0 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
238f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
23900 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
23910 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
23920 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
23930 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
23940 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
23950 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
23960 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
23970 2a 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b  * {H11332} The [
23980 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
23990 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
239a0 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
239b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
239c0 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74            back t
239d0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
239e0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
239f0 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49  **.** {H11334} I
23a00 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
23a10 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
23a20 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
23a30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
23a40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23a50 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
23a60 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
23a70 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
23a80 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
23a90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
23aa0 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
23ab0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
23ac0 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20  on S,.**        
23ad0 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
23ae0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
23af0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
23b00 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66  *.** {H11336} If
23b10 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
23b20 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
23b30 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
23b40 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
23b50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23b60 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
23b70 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
23b80 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
23b90 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
23ba0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
23bb0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
23bc0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38  ]..**.** {H11338
23bd0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
23be0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
23bf0 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
23c00 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
23c10 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79            of any
23c20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
23c30 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
23c40 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
23c50 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
23c60 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
23c70 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
23c80 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
23c90 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
23ca0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
23cb0 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 30  Functions {H1610
23cc0 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b  0} <S20200>.** K
23cd0 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
23ce0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
23cf0 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
23d00 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
23d10 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
23d20 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
23d30 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
23d40 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
23d50 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
23d60 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  se two functions
23d70 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
23d80 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
23d90 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
23da0 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
23db0 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
23dc0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
23dd0 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
23de0 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
23df0 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
23e00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
23e10 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
23e20 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
23e30 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a  e between the.**
23e40 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65   two is that the
23e50 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
23e60 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r, the name of t
23e70 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63  he (scalar) func
23e80 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
23e90 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64  gate, is encoded
23ea0 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71   in UTF-8 for sq
23eb0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
23ec0 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d  ction() and UTF-
23ed0 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  16.** for sqlite
23ee0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
23ef0 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  n16()..**.** The
23f00 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
23f10 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
23f20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
23f30 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
23f40 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
23f50 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 61   be added.  If a
23f60 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20   single program 
23f70 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
23f80 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
23f90 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e  onnection intern
23fa0 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 66  ally, then SQL f
23fb0 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
23fc0 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61   added individua
23fd0 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64  lly to.** each d
23fe0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23ff0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  on..**.** The se
24000 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
24010 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
24020 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
24030 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
24040 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 54  ** redefined.  T
24050 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
24060 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
24070 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65   to 255 bytes, e
24080 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74  xclusive of.** t
24090 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
240a0 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  or.  Note that t
240b0 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c  he name length l
240c0 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73  imit is in bytes
240d0 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74  , not.** charact
240e0 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70  ers.  Any attemp
240f0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
24100 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
24110 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
24120 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
24130 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67  ITE_ERROR] being
24140 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
24150 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
24160 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69  eter (nArg).** i
24170 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
24180 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
24190 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
241a0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
241b0 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70  takes. If this p
241c0 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
241d0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
241e0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
241f0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
24200 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
24210 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
24220 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
24230 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
24240 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
24250 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
24260 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
24270 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
24280 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
24290 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
242a0 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
242b0 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
242c0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
242d0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
242e0 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
242f0 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
24300 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
24310 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
24320 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
24330 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
24340 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
24350 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f   Any SQL functio
24360 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
24370 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20   should be able 
24380 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20  to work.** work 
24390 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
243a0 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
243b0 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
243c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
243d0 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
243e0 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
243f0 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
24400 74 68 65 72 2e 20 20 41 6e 20 61 70 70 6c 69 63  ther.  An applic
24410 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76  ation may.** inv
24420 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
24430 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
24440 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
24450 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
24460 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
24470 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
24480 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
24490 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
244a0 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
244b0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
244c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
244d0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
244e0 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
244f0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
24500 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
24510 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
24520 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
24530 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
24540 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
24550 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
24560 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
24570 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
24580 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
24590 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
245a0 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
245b0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
245c0 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
245d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
245e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
245f0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
24600 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
24610 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
24620 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
24630 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
24640 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
24650 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
24660 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  ata()]..**.** Th
24670 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74  e seventh, eight
24680 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61  h and ninth para
24690 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
246a0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
246b0 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
246c0 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
246d0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
246e0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
246f0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
24700 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c  ggregate. A scal
24710 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
24720 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
24730 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
24740 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
24750 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70  ack only, NULL p
24760 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62  ointers should b
24770 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
24780 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
24790 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
247a0 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
247b0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
247c0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
247d0 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
247e0 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
247f0 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70  NULL should be p
24800 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
24810 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78   To delete an ex
24820 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
24830 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
24840 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66  ate, pass NULL f
24850 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
24860 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e  ction callbacks.
24870 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72  .**.** It is per
24880 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
24890 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
248a0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
248b0 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
248c0 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
248d0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
248e0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
248f0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
24900 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
24910 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
24920 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
24930 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73    SQLite will us
24940 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
24950 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73  ntation that mos
24960 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
24970 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
24980 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
24990 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20  nction is used. 
249a0 20 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   A function impl
249b0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
249c0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
249d0 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
249e0 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
249f0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
24a00 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
24a10 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
24a20 74 69 76 65 20 6e 41 72 67 2e 20 20 41 20 66 75  tive nArg.  A fu
24a30 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
24a40 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
24a50 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
24a60 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
24a70 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
24a80 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
24a90 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
24aa0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
24ab0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
24ac0 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e 20   .** A function 
24ad0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
24ae0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
24af0 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
24b00 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
24b10 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
24b20 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
24b30 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
24b40 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
24b50 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
24b60 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
24b70 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75 6e  .** Built-in fun
24b80 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
24b90 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
24ba0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
24bb0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
24bc0 2a 20 54 68 65 20 66 69 72 73 74 20 61 70 70 6c  * The first appl
24bd0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
24be0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
24bf0 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72  given name overr
24c00 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c  ides all.** buil
24c10 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69  t-in functions i
24c20 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
24c30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
24c40 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
24c50 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  ame..** Subseque
24c60 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  nt application-d
24c70 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
24c80 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   of the same nam
24c90 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 20  e only override 
24ca0 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 63  .** prior applic
24cb0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
24cc0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  nctions that are
24cd0 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68 20   an exact match 
24ce0 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  for the.** numbe
24cf0 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20  r of parameters 
24d00 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65 6e  and preferred en
24d10 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e  coding..**.** An
24d20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
24d30 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
24d40 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
24d50 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
24d60 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
24d70 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
24d80 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
24d90 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
24da0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
24db0 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
24dc0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
24dd0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
24de0 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
24df0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
24e00 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
24e10 74 73 3a 0a 2a 2a 20 5b 48 31 36 31 30 33 5d 20  ts:.** [H16103] 
24e20 5b 48 31 36 31 30 36 5d 20 5b 48 31 36 31 30 39  [H16106] [H16109
24e30 5d 20 5b 48 31 36 31 31 32 5d 20 5b 48 31 36 31  ] [H16112] [H161
24e40 31 38 5d 20 5b 48 31 36 31 32 31 5d 20 5b 48 31  18] [H16121] [H1
24e50 36 31 32 37 5d 0a 2a 2a 20 5b 48 31 36 31 33 30  6127].** [H16130
24e60 5d 20 5b 48 31 36 31 33 33 5d 20 5b 48 31 36 31  ] [H16133] [H161
24e70 33 36 5d 20 5b 48 31 36 31 33 39 5d 20 5b 48 31  36] [H16139] [H1
24e80 36 31 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6142].*/.int sql
24e90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
24ea0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
24eb0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
24ec0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
24ed0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
24ee0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
24ef0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
24f00 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
24f10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
24f20 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
24f30 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
24f40 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
24f50 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
24f60 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
24f70 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
24f80 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
24f90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
24fa0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
24fb0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
24fc0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
24fd0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
24fe0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
24ff0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
25000 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
25010 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
25020 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
25030 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
25040 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
25050 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
25060 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
25070 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
25080 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
25090 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ext*).);../*.** 
250a0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
250b0 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36 37  ncodings {H10267
250c0 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36 31  } <S50200> <H161
250d0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
250e0 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
250f0 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
25100 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
25110 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
25120 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
25130 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
25140 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
25150 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
25160 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
25170 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
25180 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
25190 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
251a0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
251b0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
251c0 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
251d0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
251e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
251f0 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
25200 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  5    /* sqlite3_
25210 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20  create_function 
25220 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
25230 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
25240 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
25250 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
25260 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
25270 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25280 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74  Deprecated Funct
25290 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54  ions.** DEPRECAT
252a0 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ED.**.** These f
252b0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65  unctions are [de
252c0 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f  precated].  In o
252d0 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
252e0 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
252f0 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
25300 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65   older code, the
25310 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e  se functions con
25320 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20  tinue .** to be 
25330 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65  supported.  Howe
25340 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61  ver, new applica
25350 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f  tions should avo
25360 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
25370 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
25380 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
25390 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
253a0 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
253b0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
253c0 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
253d0 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74  to tell you what
253e0 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
253f0 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
25400 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
25410 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
25420 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
25430 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
25440 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
25450 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
25460 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
25470 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
25480 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
25490 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
254a0 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
254b0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
254c0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
254d0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
254e0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
254f0 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
25500 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
25510 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
25520 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
25530 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nup(void);.SQLIT
25540 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
25550 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
25560 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
25570 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
25580 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c  4,int),void*,sql
25590 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
255a0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
255b0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
255c0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
255d0 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48 31  meter Values {H1
255e0 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  5100} <S20200>.*
255f0 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
25600 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
25610 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
25620 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
25630 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
25640 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
25650 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
25660 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
25670 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
25680 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
25690 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ggregate..**.** 
256a0 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
256b0 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
256c0 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
256d0 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
256e0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
256f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
25700 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
25710 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
25720 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
25730 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
25740 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
25750 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
25760 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
25770 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65  * The 4th parame
25780 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
25790 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
257a0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
257b0 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
257c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
257d0 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
257e0 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
257f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
25800 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
25810 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
25820 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
25830 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
25840 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
25850 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
25860 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
25870 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
25880 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
25890 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
258a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
258b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
258c0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
258d0 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
258e0 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
258f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
25900 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
25910 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
25920 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
25930 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
25940 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
25950 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
25960 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
25970 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
25980 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
25990 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
259a0 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
259b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
259c0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
259d0 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
259e0 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
259f0 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
25a00 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
25a10 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
25a20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
25a30 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
25a40 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
25a50 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
25a60 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
25a70 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
25a80 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
25a90 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
25aa0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
25ab0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
25ac0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
25ad0 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
25ae0 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
25af0 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
25b00 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
25b10 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
25b20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25b30 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
25b40 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
25b50 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
25b60 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
25b70 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
25b80 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
25b90 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
25ba0 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
25bb0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
25bc0 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
25bd0 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
25be0 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
25bf0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
25c00 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
25c10 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
25c20 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
25c30 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
25c40 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
25c50 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
25c60 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
25c70 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
25c80 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
25c90 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
25ca0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
25cb0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
25cc0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
25cd0 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
25ce0 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
25cf0 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ..**.** Please p
25d00 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
25d10 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
25d20 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
25d30 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
25d40 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
25d50 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
25d60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
25d70 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
25d80 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
25d90 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
25da0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
25db0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
25dc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
25dd0 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
25de0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
25df0 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
25e00 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
25e10 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
25e20 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
25e30 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
25e40 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
25e50 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
25e60 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
25e70 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
25e80 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
25e90 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
25ea0 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a  ] parameters..**
25eb0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
25ec0 3a 0a 2a 2a 20 5b 48 31 35 31 30 33 5d 20 5b 48  :.** [H15103] [H
25ed0 31 35 31 30 36 5d 20 5b 48 31 35 31 30 39 5d 20  15106] [H15109] 
25ee0 5b 48 31 35 31 31 32 5d 20 5b 48 31 35 31 31 35  [H15112] [H15115
25ef0 5d 20 5b 48 31 35 31 31 38 5d 20 5b 48 31 35 31  ] [H15118] [H151
25f00 32 31 5d 20 5b 48 31 35 31 32 34 5d 0a 2a 2a 20  21] [H15124].** 
25f10 5b 48 31 35 31 32 37 5d 20 5b 48 31 35 31 33 30  [H15127] [H15130
25f20 5d 20 5b 48 31 35 31 33 33 5d 20 5b 48 31 35 31  ] [H15133] [H151
25f30 33 36 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  36].*/.const voi
25f40 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
25f50 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
25f60 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
25f70 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
25f80 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
25f90 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
25fa0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
25fb0 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
25fc0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
25fd0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
25fe0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
25ff0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
26000 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
26010 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
26020 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
26030 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
26040 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
26050 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
26060 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
26070 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
26080 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
26090 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
260a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
260b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
260c0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
260d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
260e0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
260f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
26100 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
26110 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
26120 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
26130 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
26140 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
26150 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
26160 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
26170 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
26180 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
26190 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
261a0 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30  {H16210} <S20200
261b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  >.**.** The impl
261c0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
261d0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
261e0 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
261f0 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
26200 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
26210 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
26220 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
26230 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
26240 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
26250 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
26260 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
26270 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69  d for a.** parti
26280 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c  cular aggregate,
26290 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65   SQLite allocate
262a0 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f  s nBytes of memo
262b0 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
262c0 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61  hat.** memory, a
262d0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
262e0 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73  nter to it. On s
262f0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
26300 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
26310 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
26320 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
26330 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
26340 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64  ate function ind
26350 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ex,.** the same 
26360 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
26370 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ed. The implemen
26380 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67  tation of the ag
26390 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a  gregate can use.
263a0 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  ** the returned 
263b0 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75  buffer to accumu
263c0 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  late data..**.**
263d0 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
263e0 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
263f0 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72  allocated buffer
26400 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
26410 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e  ate.** query con
26420 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
26430 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
26440 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f  r should be a co
26450 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
26460 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
26470 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
26480 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
26490 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
264a0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
264b0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
264c0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
264d0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
264e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
264f0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
26500 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
26510 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
26520 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
26530 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
26540 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
26550 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
26560 73 3a 0a 2a 2a 20 5b 48 31 36 32 31 31 5d 20 5b  s:.** [H16211] [
26570 48 31 36 32 31 33 5d 20 5b 48 31 36 32 31 35 5d  H16213] [H16215]
26580 20 5b 48 31 36 32 31 37 5d 0a 2a 2f 0a 76 6f 69   [H16217].*/.voi
26590 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
265a0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
265b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
265c0 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
265d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
265e0 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
265f0 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c 53  ions {H16240} <S
26600 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
26610 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
26620 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
26630 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
26640 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
26650 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
26660 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
26670 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
26680 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
26690 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
266a0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
266b0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
266c0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
266d0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
266e0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
266f0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
26700 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
26710 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a  unction. {END}.*
26720 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
26730 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
26740 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
26750 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
26760 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
26770 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
26780 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
26790 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
267a0 73 3a 0a 2a 2a 20 5b 48 31 36 32 34 33 5d 0a 2a  s:.** [H16243].*
267b0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
267c0 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
267d0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
267e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
267f0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
26800 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20  n For Functions 
26810 7b 48 31 36 32 35 30 7d 20 3c 53 36 30 36 30 30  {H16250} <S60600
26820 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S20200>.**.** 
26830 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
26840 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
26850 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
26860 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
26870 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
26880 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
26890 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
268a0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
268b0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
268c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
268d0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
268e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
268f0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
26900 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
26910 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
26920 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
26930 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
26940 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
26950 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 35 33 5d 0a  ts:.** [H16253].
26960 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
26970 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
26980 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
26990 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
269a0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
269b0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
269c0 61 20 7b 48 31 36 32 37 30 7d 20 3c 53 32 30 32  a {H16270} <S202
269d0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  00>.**.** The fo
269e0 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63  llowing two func
269f0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
26a00 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20  d by scalar SQL 
26a10 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
26a20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
26a30 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
26a40 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
26a50 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
26a60 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
26a70 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
26a80 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
26a90 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
26aa0 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
26ab0 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
26ac0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
26ad0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
26ae0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
26af0 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
26b00 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
26b10 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
26b20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
26b30 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
26b40 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
26b50 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
26b60 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
26b70 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
26b80 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
26b90 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
26ba0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51  ated with the SQ
26bb0 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  L value passed a
26bc0 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  s the regular ex
26bd0 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74  pression.** patt
26be0 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c  ern.  The compil
26bf0 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
26c00 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
26c10 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
26c20 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
26c30 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
26c40 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20  ion so that the 
26c50 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e  original pattern
26c60 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20   string.** does 
26c70 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72  not need to be r
26c80 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63  ecompiled on eac
26c90 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  h invocation..**
26ca0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
26cb0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
26cc0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
26cd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
26ce0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
26cf0 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
26d00 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
26d10 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
26d20 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
26d30 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
26d40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
26d50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
26d60 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61  . If no metadata
26d70 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a   has been ever.*
26d80 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  * been set for t
26d90 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
26da0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
26db0 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65   or if the corre
26dc0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63  sponding.** func
26dd0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68  tion parameter h
26de0 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
26df0 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
26e00 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20  as set,.** then 
26e10 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
26e20 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20  ata() returns a 
26e30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
26e40 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
26e50 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
26e60 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
26e70 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f  e metadata.** po
26e80 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
26e90 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
26ea0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f   the metadata fo
26eb0 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
26ec0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
26ed0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26ee0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62  d function.  Sub
26ef0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
26f00 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
26f10 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
26f20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
26f30 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
26f40 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
26f50 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20 6e  d..** If it is n
26f60 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
26f70 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
26f80 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
26f90 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
26fa0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
26fb0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
26fc0 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
26fd0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
26fe0 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
26ff0 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
27000 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
27010 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
27020 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
27030 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
27040 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
27050 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
27060 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
27070 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
27080 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
27090 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
270a0 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
270b0 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54   at any time.  T
270c0 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
270d0 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  e is that.** the
270e0 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
270f0 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
27100 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
27110 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  s dropped..**.**
27120 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65   In practice, me
27130 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
27140 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
27150 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
27160 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
27170 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
27180 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
27190 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
271a0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
271b0 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c   and SQL variabl
271c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es..**.** These 
271d0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
271e0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
271f0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
27200 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
27210 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
27220 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ning..**.** Requ
27230 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
27240 36 32 37 32 5d 20 5b 48 31 36 32 37 34 5d 20 5b  6272] [H16274] [
27250 48 31 36 32 37 36 5d 20 5b 48 31 36 32 37 37 5d  H16276] [H16277]
27260 20 5b 48 31 36 32 37 38 5d 20 5b 48 31 36 32 37   [H16278] [H1627
27270 39 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  9].*/.void *sqli
27280 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
27290 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
272a0 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73  , int N);.void s
272b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
272c0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
272d0 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
272e0 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
272f0 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
27300 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
27310 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
27320 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
27330 61 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c  avior {H10280} <
27340 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30100>.**.** Th
27350 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
27360 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
27370 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
27380 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
27390 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
273a0 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
273b0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
273c0 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
273d0 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
273e0 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
273f0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
27400 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
27410 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
27420 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
27430 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
27440 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
27450 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
27460 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 0a  destroyed.  The.
27470 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
27480 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
27490 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
274a0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
274b0 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
274c0 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
274d0 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
274e0 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
274f0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
27500 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
27510 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
27520 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
27530 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
27540 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
27550 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
27560 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
27570 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23  s.  See ticket #
27580 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  2191..*/.typedef
27590 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
275a0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
275b0 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
275c0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
275d0 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
275e0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
275f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27600 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
27610 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
27620 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
27630 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
27640 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
27650 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
27660 20 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32 30   {H16400} <S2020
27670 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
27680 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
27690 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
276a0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
276b0 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
276c0 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
276d0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
276e0 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
276f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
27700 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
27710 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
27720 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
27730 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
27740 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
27750 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
27760 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
27770 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
27780 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
27790 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
277a0 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
277b0 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
277c0 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
277d0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
277e0 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
277f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
27800 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
27810 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
27820 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
27830 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
27840 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
27850 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
27860 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
27870 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
27880 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
27890 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
278a0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
278b0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
278c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
278d0 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
278e0 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
278f0 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
27900 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
27910 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27920 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
27930 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
27940 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
27950 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
27960 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
27970 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
27980 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
27990 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
279a0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
279b0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
279c0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
279d0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
279e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
279f0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69  esult_double() i
27a00 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
27a10 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
27a20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
27a30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
27a40 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e   to be a floatin
27a50 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70  g point value sp
27a60 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74  ecified.** by it
27a70 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  s 2nd argument..
27a80 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27a90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
27aa0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
27ab0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
27ac0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
27ad0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
27ae0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
27af0 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
27b00 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ion..** SQLite u
27b10 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
27b20 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
27b30 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
27b40 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
27b50 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
27b60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
27b70 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
27b80 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
27b90 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c  or message.  SQL
27ba0 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
27bb0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
27bc0 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
27bd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
27be0 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
27bf0 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72   SQLite.** inter
27c00 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67  prets the string
27c10 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
27c20 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61  sult_error16() a
27c30 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  s UTF-16 in nati
27c40 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72  ve.** byte order
27c50 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 20  .  If the third 
27c60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
27c70 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
27c80 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
27c90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
27ca0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
27cb0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
27cc0 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
27cd0 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
27ce0 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
27cf0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
27d00 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65  acter..** If the
27d10 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
27d20 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
27d30 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
27d40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27d50 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
27d60 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
27d70 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
27d80 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
27d90 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
27da0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
27db0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
27dc0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
27dd0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
27de0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
27df0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
27e00 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
27e10 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
27e20 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
27e30 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
27e40 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
27e50 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
27e60 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
27e70 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
27e80 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
27e90 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
27ea0 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
27eb0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68  hout harm..** Th
27ec0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
27ed0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
27ee0 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
27ef0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
27f00 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
27f10 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
27f20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
27f30 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64   function.  By d
27f40 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
27f50 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
27f60 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75  ITE_ERROR.  A su
27f70 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
27f80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27f90 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
27fa0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
27fb0 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68  or16() resets th
27fc0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20  e error code to 
27fd0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a  SQLITE_ERROR..**
27fe0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27ff0 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
28000 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
28010 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
28020 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
28030 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
28040 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
28050 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72   to long to repr
28060 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  esent..**.** The
28070 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28080 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
28090 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
280a0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
280b0 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
280c0 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
280d0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
280e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
280f0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
28100 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
28110 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
28120 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
28130 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
28140 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
28150 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
28160 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
28170 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
28180 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
28190 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
281a0 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
281b0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
281c0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
281d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
281e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
281f0 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
28200 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
28210 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
28220 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
28230 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nt..**.** The sq
28240 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
28250 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  l() interface se
28260 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
28270 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
28280 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
28290 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
282a0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
282b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
282c0 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
282d0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
282e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
282f0 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
28300 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
28310 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
28320 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
28330 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
28340 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
28350 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
28360 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
28370 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
28380 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
28390 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
283a0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
283b0 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
283c0 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
283d0 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
283e0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
283f0 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73  .** SQLite takes
28400 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
28410 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
28420 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
28430 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
28440 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
28450 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
28460 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68  rfaces..** If th
28470 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
28480 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
28490 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
284a0 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67  rfaces.** is neg
284b0 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69  ative, then SQLi
284c0 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20  te takes result 
284d0 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e  text from the 2n
284e0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
284f0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
28500 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
28510 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
28520 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
28530 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
28540 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
28550 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
28560 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
28570 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
28580 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
28590 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
285a0 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
285b0 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
285c0 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
285d0 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
285e0 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a  unction result..
285f0 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61  ** If the 4th pa
28600 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
28610 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
28620 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
28630 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
28640 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
28650 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
28660 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
28670 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
28680 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
28690 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
286a0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
286b0 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
286c0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
286d0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66  at result..** If
286e0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
286f0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
28700 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
28710 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a  nterfaces or to.
28720 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
28730 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
28740 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
28750 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
28760 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
28770 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
28780 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
28790 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
287a0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
287b0 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
287c0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70  content of the p
287d0 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c  arameter nor cal
287e0 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f  l a destructor o
287f0 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a  n the content.**
28800 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
28810 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
28820 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74   result..** If t
28830 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
28840 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
28850 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
28860 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
28870 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
28880 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
28890 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
288a0 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
288b0 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
288c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
288d0 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
288e0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
288f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
28900 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
28910 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
28920 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
28930 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
28940 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
28950 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
28960 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
28970 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
28980 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
28990 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
289a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
289b0 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
289c0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
289d0 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ter.  The.** sql
289e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
289f0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
28a00 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
28a10 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
28a20 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
28a30 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
28a40 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
28a50 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
28a60 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
28a70 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
28a80 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
28a90 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
28aa0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
28ab0 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73  * A [protected s
28ac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
28ad0 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
28ae0 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
28af0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
28b00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
28b10 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
28b20 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
28b30 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
28b40 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
28b50 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
28b60 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
28b70 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
28b80 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
28b90 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
28ba0 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
28bb0 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
28bc0 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
28bd0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
28be0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
28bf0 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
28c00 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
28c10 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
28c20 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
28c30 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
28c40 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
28c50 2a 2a 20 5b 48 31 36 34 30 33 5d 20 5b 48 31 36  ** [H16403] [H16
28c60 34 30 36 5d 20 5b 48 31 36 34 30 39 5d 20 5b 48  406] [H16409] [H
28c70 31 36 34 31 32 5d 20 5b 48 31 36 34 31 35 5d 20  16412] [H16415] 
28c80 5b 48 31 36 34 31 38 5d 20 5b 48 31 36 34 32 31  [H16418] [H16421
28c90 5d 20 5b 48 31 36 34 32 34 5d 0a 2a 2a 20 5b 48  ] [H16424].** [H
28ca0 31 36 34 32 37 5d 20 5b 48 31 36 34 33 30 5d 20  16427] [H16430] 
28cb0 5b 48 31 36 34 33 33 5d 20 5b 48 31 36 34 33 36  [H16433] [H16436
28cc0 5d 20 5b 48 31 36 34 33 39 5d 20 5b 48 31 36 34  ] [H16439] [H164
28cd0 34 32 5d 20 5b 48 31 36 34 34 35 5d 20 5b 48 31  42] [H16445] [H1
28ce0 36 34 34 38 5d 0a 2a 2a 20 5b 48 31 36 34 35 31  6448].** [H16451
28cf0 5d 20 5b 48 31 36 34 35 34 5d 20 5b 48 31 36 34  ] [H16454] [H164
28d00 35 37 5d 20 5b 48 31 36 34 36 30 5d 20 5b 48 31  57] [H16460] [H1
28d10 36 34 36 33 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71  6463].*/.void sq
28d20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
28d30 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
28d40 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
28d50 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
28d60 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
28d70 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
28d80 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
28d90 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
28da0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
28db0 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
28dc0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
28dd0 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
28de0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28df0 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
28e00 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
28e10 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
28e20 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
28e30 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
28e40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
28e50 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
28e60 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
28e70 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28e80 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
28e90 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
28ea0 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
28eb0 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
28ec0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
28ed0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
28ee0 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
28ef0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
28f00 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
28f10 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
28f20 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
28f30 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
28f40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
28f50 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
28f60 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
28f70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
28f80 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
28f90 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
28fa0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
28fb0 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
28fc0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
28fd0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
28fe0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
28ff0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
29000 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
29010 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
29020 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
29030 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
29040 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
29050 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
29060 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
29070 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
29080 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
29090 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
290a0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
290b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
290c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
290d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
290e0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
290f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
29100 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
29110 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
29120 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
29130 75 65 6e 63 65 73 20 7b 48 31 36 36 30 30 7d 20  uences {H16600} 
29140 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20300>.**.** T
29150 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
29160 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e  re used to add n
29170 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
29180 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a  uences to the.**
29190 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
291a0 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
291b0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
291c0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
291d0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65  e name of the ne
291e0 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
291f0 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65  ence is specifie
29200 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72  d as a UTF-8 str
29210 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
29220 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
29230 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
29240 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
29250 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
29260 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66   UTF-16 string f
29270 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
29280 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
29290 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a   In all cases.**
292a0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73   the name is pas
292b0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
292c0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
292d0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ent..**.** The t
292e0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61  hird argument ma
292f0 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  y be one of the 
29300 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
29310 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
29320 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 6f 72  ITE_UTF16LE], or
29330 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
29340 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
29350 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70  at the user-supp
29360 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  lied.** routine 
29370 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61  expects to be pa
29380 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f  ssed pointers to
29390 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64   strings encoded
293a0 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a   using UTF-8,.**
293b0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65   UTF-16 little-e
293c0 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
293d0 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73   big-endian, res
293e0 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a  pectively. The.*
293f0 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  * third argument
29400 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b   might also be [
29410 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 74 6f  SQLITE_UTF16] to
29420 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 74   indicate that t
29430 68 65 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65 78  he routine.** ex
29440 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
29450 6f 20 62 65 20 55 54 46 2d 31 36 20 73 74 72 69  o be UTF-16 stri
29460 6e 67 73 20 69 6e 20 74 68 65 20 6e 61 74 69 76  ngs in the nativ
29470 65 20 62 79 74 65 20 6f 72 64 65 72 2c 20 6f 72  e byte order, or
29480 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
29490 20 63 61 6e 20 62 65 20 5b 53 51 4c 49 54 45 5f   can be [SQLITE_
294a0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 69  UTF16_ALIGNED] i
294b0 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f 75  f the.** the rou
294c0 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69  tine expects poi
294d0 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20  nters to 16-bit 
294e0 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72  word aligned str
294f0 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31  ings.** of UTF-1
29500 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
29510 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
29520 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
29530 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64  he user supplied
29540 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
29550 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
29560 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ifth.** argument
29570 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  .  If it is NULL
29580 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61  , this is the sa
29590 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74  me as deleting t
295a0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
295b0 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61  sequence (so tha
295c0 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20  t SQLite cannot 
295d0 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29  call it anymore)
295e0 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74  ..** Each time t
295f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
29600 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e  upplied function
29610 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20   is invoked, it 
29620 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20  is passed.** as 
29630 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  its first parame
29640 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ter a copy of th
29650 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61  e void* passed a
29660 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  s the fourth arg
29670 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
29680 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
29690 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
296a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
296b0 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  on16()..**.** Th
296c0 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75  e remaining argu
296d0 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70  ments to the app
296e0 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
296f0 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
29700 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
29710 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
29720 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74  y a (length, dat
29730 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a) pair and enco
29740 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
29750 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
29760 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
29770 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
29780 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
29790 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
297a0 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44  registered. {END
297b0 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  }  The applicati
297c0 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61  on defined colla
297d0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f  tion routine sho
297e0 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65  uld.** return ne
297f0 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20  gative, zero or 
29800 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 20  positive if the 
29810 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
29820 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71  less than,.** eq
29830 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
29840 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
29850 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20  nd string. i.e. 
29860 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e  (STRING1 - STRIN
29870 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  G2)..**.** The s
29880 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
29890 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
298a0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
298b0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
298c0 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
298d0 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78  t it takes an ex
298e0 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69  tra argument whi
298f0 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ch is a destruct
29900 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f  or for.** the co
29910 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  llation.  The de
29920 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
29930 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  ed when the coll
29940 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74  ation is.** dest
29950 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73  royed and is pas
29960 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68  sed a copy of th
29970 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
29980 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  er void* pointer
29990 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
299a0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
299b0 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c  ion_v2()..** Col
299c0 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74  lations are dest
299d0 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 20  royed when they 
299e0 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
299f0 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f  y later calls to
29a00 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f   the.** collatio
29a10 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
29a20 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65  ions or when the
29a30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
29a40 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64  ction] is closed
29a50 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
29a60 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
29a70 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73  ** See also:  [s
29a80 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
29a90 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b  _needed()] and [
29aa0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
29ab0 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a  n_needed16()]..*
29ac0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
29ad0 73 3a 0a 2a 2a 20 5b 48 31 36 36 30 33 5d 20 5b  s:.** [H16603] [
29ae0 48 31 36 36 30 34 5d 20 5b 48 31 36 36 30 36 5d  H16604] [H16606]
29af0 20 5b 48 31 36 36 30 39 5d 20 5b 48 31 36 36 31   [H16609] [H1661
29b00 32 5d 20 5b 48 31 36 36 31 35 5d 20 5b 48 31 36  2] [H16615] [H16
29b10 36 31 38 5d 20 5b 48 31 36 36 32 31 5d 0a 2a 2a  618] [H16621].**
29b20 20 5b 48 31 36 36 32 34 5d 20 5b 48 31 36 36 32   [H16624] [H1662
29b30 37 5d 20 5b 48 31 36 36 33 30 5d 0a 2a 2f 0a 69  7] [H16630].*/.i
29b40 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
29b50 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
29b60 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
29b70 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
29b80 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
29b90 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
29ba0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
29bb0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
29bc0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
29bd0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
29be0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
29bf0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
29c00 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
29c10 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
29c20 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
29c30 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
29c40 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
29c50 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
29c60 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
29c70 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
29c80 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
29c90 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
29ca0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
29cb0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
29cc0 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
29cd0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
29ce0 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
29cf0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
29d00 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
29d10 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
29d20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29d30 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
29d40 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37   Callbacks {H167
29d50 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a  00} <S20300>.**.
29d60 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69  ** To avoid havi
29d70 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ng to register a
29d80 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ll collation seq
29d90 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20  uences before a 
29da0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20  database.** can 
29db0 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c  be used, a singl
29dc0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
29dd0 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
29de0 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a  tered with the.*
29df0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
29e00 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61  ection] to be ca
29e10 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  lled whenever an
29e20 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
29e30 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
29e40 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
29e50 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74  .** If the funct
29e60 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
29e70 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
29e80 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
29e90 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
29ea0 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
29eb0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
29ec0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
29ed0 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
29ee0 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
29ef0 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36  d in UTF-8. {H16
29f00 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f  703} If sqlite3_
29f10 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
29f20 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
29f30 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
29f40 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
29f50 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
29f60 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
29f70 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65   A call to eithe
29f80 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  r function repla
29f90 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67  ces any existing
29fa0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
29fb0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
29fc0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
29fd0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
29fe0 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
29ff0 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
2a000 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
2a010 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2a020 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
2a030 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2a040 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
2a050 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
2a060 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
2a070 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2a080 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
2a090 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
2a0a0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
2a0b0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2a0c0 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
2a0d0 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
2a0e0 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
2a0f0 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
2a100 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
2a110 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
2a120 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
2a130 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2a140 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
2a150 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
2a160 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
2a170 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ence..**.** The 
2a180 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2a190 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65  n should registe
2a1a0 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f  r the desired co
2a1b0 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  llation using.**
2a1c0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2a1d0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b  _collation()], [
2a1e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2a1f0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  ollation16()], o
2a200 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
2a210 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2a220 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  2()]..**.** Requ
2a230 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
2a240 36 37 30 32 5d 20 5b 48 31 36 37 30 34 5d 20 5b  6702] [H16704] [
2a250 48 31 36 37 30 36 5d 0a 2a 2f 0a 69 6e 74 20 73  H16706].*/.int s
2a260 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2a270 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
2a280 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
2a290 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
2a2a0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
2a2b0 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
2a2c0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2a2d0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2a2e0 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
2a2f0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
2a300 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2a310 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
2a320 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
2a330 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
2a340 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
2a350 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
2a360 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
2a370 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
2a380 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
2a390 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
2a3a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
2a3b0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
2a3c0 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
2a3d0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
2a3e0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
2a3f0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
2a400 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a  nt sqlite3_key(.
2a410 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2a420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a430 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
2a440 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
2a450 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
2a460 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
2a470 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
2a480 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68  ./*.** Change th
2a490 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e  e key on an open
2a4a0 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74   database.  If t
2a4b0 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
2a4c0 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e  ase is not.** en
2a4d0 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f  crypted, this ro
2a4e0 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79  utine will encry
2a4f0 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d  pt it.  If pNew=
2a500 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74  =0 or nNew==0, t
2a510 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69  he.** database i
2a520 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a  s decrypted..**.
2a530 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
2a540 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
2a550 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
2a560 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
2a570 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
2a580 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
2a590 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73  lite3_rekey(.  s
2a5a0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2a5b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2a5c0 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
2a5d0 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
2a5e0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
2a5f0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
2a600 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
2a610 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a620 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74  : Suspend Execut
2a630 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
2a640 54 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53  Time {H10530} <S
2a650 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  40410>.**.** The
2a660 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
2a670 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
2a680 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
2a690 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65  ead to suspend e
2a6a0 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  xecution.** for 
2a6b0 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65  at least a numbe
2a6c0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
2a6d0 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
2a6e0 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
2a6f0 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61  .** If the opera
2a700 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73  ting system does
2a710 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65   not support sle
2a720 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68  ep requests with
2a730 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20  .** millisecond 
2a740 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  time resolution,
2a750 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77   then the time w
2a760 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75  ill be rounded u
2a770 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72  p to.** the near
2a780 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20  est second. The 
2a790 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
2a7a0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20  econds of sleep 
2a7b0 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75  actually.** requ
2a7c0 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f  ested from the o
2a7d0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
2a7e0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2a7f0 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
2a800 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
2a810 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
2a820 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
2a830 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
2a840 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
2a850 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  s] object..**.**
2a860 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
2a870 48 31 30 35 33 33 5d 20 5b 48 31 30 35 33 36 5d  H10533] [H10536]
2a880 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2a890 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
2a8a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
2a8b0 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
2a8c0 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
2a8d0 79 20 46 69 6c 65 73 20 7b 48 31 30 33 31 30 7d  y Files {H10310}
2a8e0 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
2a8f0 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
2a900 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
2a910 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
2a920 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
2a930 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
2a940 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
2a950 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
2a960 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
2a970 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
2a980 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
2a990 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
2a9a0 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68  irectory.  If th
2a9b0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
2a9c0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2a9d0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
2a9e0 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
2a9f0 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
2aa00 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
2aa10 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
2aa20 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
2aa30 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
2aa40 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
2aa50 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
2aa60 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
2aa70 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
2aa80 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
2aa90 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
2aaa0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
2aab0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
2aac0 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
2aad0 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
2aae0 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
2aaf0 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
2ab00 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
2ab10 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
2ab20 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
2ab30 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
2ab40 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
2ab50 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
2ab60 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
2ab70 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
2ab80 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
2ab90 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
2aba0 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
2abb0 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
2abc0 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
2abd0 20 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   The [temp_store
2abe0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
2abf0 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
2ac00 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
2ac10 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
2ac20 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
2ac30 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2ac40 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
2ac50 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
2ac60 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
2ac70 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2ac80 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
2ac90 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
2aca0 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
2acb0 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
2acc0 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
2acd0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
2ace0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
2acf0 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
2ad00 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
2ad10 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
2ad20 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
2ad30 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
2ad40 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
2ad50 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
2ad60 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
2ad70 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
2ad80 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
2ad90 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
2ada0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
2adb0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2adc0 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
2add0 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
2ade0 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
2adf0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2ae00 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
2ae10 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ded..*/.SQLITE_E
2ae20 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
2ae30 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
2ae40 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
2ae50 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75  REF: Test For Au
2ae60 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b  to-Commit Mode {
2ae70 48 31 32 39 33 30 7d 20 3c 53 36 30 32 30 30 3e  H12930} <S60200>
2ae80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2ae90 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a  utocommit mode}.
2aea0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2aeb0 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
2aec0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2aed0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
2aee0 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
2aef0 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
2af00 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
2af10 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
2af20 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
2af30 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 75 74  spectively.  Aut
2af40 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
2af50 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
2af60 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  * Autocommit mod
2af70 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
2af80 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65   a [BEGIN] state
2af90 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d  ment..** Autocom
2afa0 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65  mit mode is re-e
2afb0 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d  nabled by a [COM
2afc0 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43  MIT] or [ROLLBAC
2afd0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72  K]..**.** If cer
2afe0 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72  tain kinds of er
2aff0 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20  rors occur on a 
2b000 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
2b010 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65   a multi-stateme
2b020 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  nt.** transactio
2b030 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64  n (errors includ
2b040 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c  ing [SQLITE_FULL
2b050 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ], [SQLITE_IOERR
2b060 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  ],.** [SQLITE_NO
2b070 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55  MEM], [SQLITE_BU
2b080 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  SY], and [SQLITE
2b090 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65  _INTERRUPT]) the
2b0a0 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63  n the.** transac
2b0b0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f  tion might be ro
2b0c0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
2b0d0 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e  tically.  The on
2b0e0 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e  ly way to.** fin
2b0f0 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51  d out whether SQ
2b100 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
2b110 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74  ly rolled back t
2b120 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61  he transaction a
2b130 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  fter.** an error
2b140 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20   is to use this 
2b150 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2b160 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
2b170 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75  d changes the au
2b180 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20  tocommit status 
2b190 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
2b1a0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  ** connection wh
2b1b0 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ile this routine
2b1c0 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65   is running, the
2b1d0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
2b1e0 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ue.** is undefin
2b1f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ed..**.** Requir
2b200 65 6d 65 6e 74 73 3a 20 5b 48 31 32 39 33 31 5d  ements: [H12931]
2b210 20 5b 48 31 32 39 33 32 5d 20 5b 48 31 32 39 33   [H12932] [H1293
2b220 33 5d 20 5b 48 31 32 39 33 34 5d 0a 2a 2f 0a 69  3] [H12934].*/.i
2b230 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  nt sqlite3_get_a
2b240 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65  utocommit(sqlite
2b250 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
2b260 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44  3REF: Find The D
2b270 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f  atabase Handle O
2b280 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
2b290 74 65 6d 65 6e 74 20 7b 48 31 33 31 32 30 7d 20  tement {H13120} 
2b2a0 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60600>.**.** T
2b2b0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
2b2c0 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
2b2d0 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
2b2e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2b2f0 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
2b300 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
2b310 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
2b320 67 73 2e 20 20 54 68 65 20 5b 64 61 74 61 62 61  gs.  The [databa
2b330 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
2b340 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
2b350 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
2b360 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  is the same [dat
2b370 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b380 5d 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66  ] that was the f
2b390 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
2b3a0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2b3b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63  _prepare_v2()] c
2b3c0 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69  all (or its vari
2b3d0 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75  ants) that was u
2b3e0 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65  sed to.** create
2b3f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2b400 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
2b410 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  e..**.** Require
2b420 6d 65 6e 74 73 3a 20 5b 48 31 33 31 32 33 5d 0a  ments: [H13123].
2b430 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
2b440 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
2b450 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2b460 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2b470 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65  ind the next pre
2b480 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2b490 7b 48 31 33 31 34 30 7d 20 3c 53 36 30 36 30 30  {H13140} <S60600
2b4a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  >.**.** This int
2b4b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2b4c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2b4d0 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73  next [prepared s
2b4e0 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a  tatement] after.
2b4f0 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61  ** pStmt associa
2b500 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
2b510 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b520 6e 5d 20 70 44 62 2e 20 20 49 66 20 70 53 74 6d  n] pDb.  If pStm
2b530 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65  t is NULL.** the
2b540 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  n this interface
2b550 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2b560 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  er to the first 
2b570 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b580 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  nt.** associated
2b590 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
2b5a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44  se connection pD
2b5b0 62 2e 20 20 49 66 20 6e 6f 20 70 72 65 70 61 72  b.  If no prepar
2b5c0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
2b5d0 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f  satisfies the co
2b5e0 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73  nditions of this
2b5f0 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74   routine, it ret
2b600 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  urns NULL..**.**
2b610 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   The [database c
2b620 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74  onnection] point
2b630 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74  er D in a call t
2b640 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65  o.** [sqlite3_ne
2b650 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75  xt_stmt(D,S)] mu
2b660 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f  st refer to an o
2b670 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  pen database.** 
2b680 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69  connection and i
2b690 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73  n particular mus
2b6a0 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20  t not be a NULL 
2b6b0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 52  pointer..**.** R
2b6c0 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31  equirements: [H1
2b6d0 33 31 34 33 5d 20 5b 48 31 33 31 34 36 5d 20 5b  3143] [H13146] [
2b6e0 48 31 33 31 34 39 5d 20 5b 48 31 33 31 35 32 5d  H13149] [H13152]
2b6f0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
2b700 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
2b710 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
2b720 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
2b730 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2b740 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
2b750 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
2b760 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
2b770 63 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 36  cks {H12950} <S6
2b780 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0400>.**.** The 
2b790 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2b7a0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
2b7b0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
2b7c0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
2b7d0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2b7e0 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
2b7f0 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54  ction is [COMMIT
2b800 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a   | committed]..*
2b810 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73  * Any callback s
2b820 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
2b830 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2b840 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
2b850 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2b860 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b870 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2b880 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
2b890 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
2b8a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
2b8b0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
2b8c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
2b8d0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
2b8e0 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
2b8f0 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20   is [ROLLBACK | 
2b900 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a  rolled back]..**
2b910 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
2b920 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
2b930 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
2b940 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a  commit_hook().**
2b950 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
2b960 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b970 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
2b980 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72 67  .** The pArg arg
2b990 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
2b9a0 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
2b9b0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 20 74  allback..** If t
2b9c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
2b9d0 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
2b9e0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f  ction returns no
2b9f0 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  n-zero,.** then 
2ba00 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
2ba10 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
2ba20 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49  ollback..**.** I
2ba30 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69  f another functi
2ba40 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c  on was previousl
2ba50 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74  y registered, it
2ba60 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20  s.** pArg value 
2ba70 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
2ba80 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
2ba90 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2baa0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70  The callback imp
2bab0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
2bac0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
2bad0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
2bae0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
2baf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
2bb00 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61  t invoked the ca
2bb10 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74  llback.  Any act
2bb20 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66  ions.** to modif
2bb30 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
2bb40 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62  onnection must b
2bb50 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  e deferred until
2bb60 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f   after the.** co
2bb70 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20  mpletion of the 
2bb80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2bb90 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
2bba0 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a  ered the commit.
2bbb0 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68  ** or rollback h
2bbc0 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74  ook in the first
2bbd0 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20   place..** Note 
2bbe0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
2bbf0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2bc00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2bc10 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
2bc20 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
2bc30 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
2bc40 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
2bc50 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
2bc60 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
2bc70 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55  Registering a NU
2bc80 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  LL function disa
2bc90 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  bles the callbac
2bca0 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  k..**.** When th
2bcb0 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61  e commit hook ca
2bcc0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
2bcd0 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
2bce0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65   [COMMIT].** ope
2bcf0 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65  ration is allowe
2bd00 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f  d to continue no
2bd10 72 6d 61 6c 6c 79 2e 20 20 49 66 20 74 68 65 20  rmally.  If the 
2bd20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72  commit hook.** r
2bd30 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
2bd40 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49   then the [COMMI
2bd50 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  T] is converted 
2bd60 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b  into a [ROLLBACK
2bd70 5d 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61  ]..** The rollba
2bd80 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b  ck hook is invok
2bd90 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b  ed on a rollback
2bda0 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66 72   that results fr
2bdb0 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68  om a commit.** h
2bdc0 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f  ook returning no
2bdd0 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20  n-zero, just as 
2bde0 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68  it would be with
2bdf0 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62   any other rollb
2be00 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74  ack..**.** For t
2be10 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
2be20 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73  his API, a trans
2be30 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74  action is said t
2be40 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72  o have been.** r
2be50 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e  olled back if an
2be60 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42   explicit "ROLLB
2be70 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69  ACK" statement i
2be80 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a  s executed, or.*
2be90 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f  * an error or co
2bea0 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20  nstraint causes 
2beb0 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c  an implicit roll
2bec0 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a  back to occur..*
2bed0 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63  * The rollback c
2bee0 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
2bef0 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
2bf00 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75  saction is.** au
2bf10 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
2bf20 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
2bf30 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf40 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
2bf50 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61  d..** The rollba
2bf60 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
2bf70 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
2bf80 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
2bf90 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  * rolled back be
2bfa0 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63  cause a commit c
2bfb0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64  allback returned
2bfc0 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74   non-zero..** <t
2bfd0 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68  odo> Check on th
2bfe0 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  is </todo>.**.**
2bff0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
2c000 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2c010 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ok()] interface.
2c020 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
2c030 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 35 31 5d  nts:.** [H12951]
2c040 20 5b 48 31 32 39 35 32 5d 20 5b 48 31 32 39 35   [H12952] [H1295
2c050 33 5d 20 5b 48 31 32 39 35 34 5d 20 5b 48 31 32  3] [H12954] [H12
2c060 39 35 35 5d 0a 2a 2a 20 5b 48 31 32 39 36 31 5d  955].** [H12961]
2c070 20 5b 48 31 32 39 36 32 5d 20 5b 48 31 32 39 36   [H12962] [H1296
2c080 33 5d 20 5b 48 31 32 39 36 34 5d 0a 2a 2f 0a 76  3] [H12964].*/.v
2c090 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
2c0a0 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
2c0b0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
2c0c0 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
2c0d0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
2c0e0 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
2c0f0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
2c100 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
2c110 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
2c120 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
2c130 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31  on Callbacks {H1
2c140 32 39 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2970} <S60400>.*
2c150 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2c160 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69  _update_hook() i
2c170 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2c180 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
2c190 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
2c1a0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2c1b0 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66  nection] identif
2c1c0 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
2c1d0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
2c1e0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2c1f0 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
2c200 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
2c210 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e  r deleted..** An
2c220 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
2c230 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
2c240 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  l to this functi
2c250 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  on.** for the sa
2c260 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2c270 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
2c280 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dden..**.** The 
2c290 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2c2a0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
2c2b0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  the function to 
2c2c0 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a  invoke when a.**
2c2d0 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
2c2e0 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
2c2f0 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eted..** The fir
2c300 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2c310 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
2c320 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
2c330 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  rd argument.** t
2c340 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  o sqlite3_update
2c350 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20  _hook()..** The 
2c360 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20  second callback 
2c370 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
2c380 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52  of [SQLITE_INSER
2c390 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45  T], [SQLITE_DELE
2c3a0 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  TE],.** or [SQLI
2c3b0 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65  TE_UPDATE], depe
2c3c0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65  nding on the ope
2c3d0 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73  ration that caus
2c3e0 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  ed the callback.
2c3f0 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
2c400 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  ..** The third a
2c410 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  nd fourth argume
2c420 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  nts to the callb
2c430 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e  ack contain poin
2c440 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  ters to the.** d
2c450 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c  atabase and tabl
2c460 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e  e name containin
2c470 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72  g the affected r
2c480 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c  ow..** The final
2c490 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65   callback parame
2c4a0 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69  ter is the [rowi
2c4b0 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a  d] of the row..*
2c4c0 2a 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66  * In the case of
2c4d0 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
2c4e0 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
2c4f0 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65  after the update
2c500 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
2c510 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68  .** The update h
2c520 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ook is not invok
2c530 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c  ed when internal
2c540 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61   system tables a
2c550 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28  re.** modified (
2c560 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74  i.e. sqlite_mast
2c570 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65  er and sqlite_se
2c580 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49  quence)..**.** I
2c590 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  n the current im
2c5a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68  plementation, th
2c5b0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a  e update hook.**
2c5c0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2c5d0 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e  when duplication
2c5e0 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
2c5f0 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a  d because of an.
2c600 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  ** [ON CONFLICT 
2c610 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45  | ON CONFLICT RE
2c620 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20  PLACE] clause.  
2c630 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61 74  Nor is the updat
2c640 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65  e hook.** invoke
2c650 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20  d when rows are 
2c660 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68  deleted using th
2c670 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  e [truncate opti
2c680 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  mization]..** Th
2c690 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66  e exceptions def
2c6a0 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 72  ined in this par
2c6b0 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 61  agraph might cha
2c6c0 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
2c6d0 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
2c6e0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
2c6f0 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c  update hook impl
2c700 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
2c710 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
2c720 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
2c730 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2c740 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
2c750 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64   invoked the upd
2c760 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61  ate hook.  Any a
2c770 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
2c780 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
2c790 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
2c7a0 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
2c7b0 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
2c7c0 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
2c7d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
2c7e0 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
2c7f0 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61 74  ggered the updat
2c800 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  e hook..** Note 
2c810 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
2c820 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2c830 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c840 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
2c850 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
2c860 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
2c870 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
2c880 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
2c890 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
2c8a0 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
2c8b0 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
2c8c0 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
2c8d0 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a  ts pArg value.**
2c8e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
2c8f0 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73  therwise NULL is
2c900 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2c910 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
2c920 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2c930 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
2c940 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2c950 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
2c960 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  s..**.** Require
2c970 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 37  ments:.** [H1297
2c980 31 5d 20 5b 48 31 32 39 37 33 5d 20 5b 48 31 32  1] [H12973] [H12
2c990 39 37 35 5d 20 5b 48 31 32 39 37 37 5d 20 5b 48  975] [H12977] [H
2c9a0 31 32 39 37 39 5d 20 5b 48 31 32 39 38 31 5d 20  12979] [H12981] 
2c9b0 5b 48 31 32 39 38 33 5d 20 5b 48 31 32 39 38 36  [H12983] [H12986
2c9c0 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ].*/.void *sqlit
2c9d0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a  e3_update_hook(.
2c9e0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2c9f0 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e  oid(*)(void *,in
2ca00 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c  t ,char const *,
2ca10 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c  char const *,sql
2ca20 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76  ite3_int64),.  v
2ca30 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  oid*.);../*.** C
2ca40 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
2ca50 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65  Or Disable Share
2ca60 64 20 50 61 67 65 72 20 43 61 63 68 65 20 7b 48  d Pager Cache {H
2ca70 31 30 33 33 30 7d 20 3c 53 33 30 39 30 30 3e 0a  10330} <S30900>.
2ca80 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68  ** KEYWORDS: {sh
2ca90 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a  ared cache}.**.*
2caa0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65  * This routine e
2cab0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
2cac0 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f  es the sharing o
2cad0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
2cae0 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65  ache.** and sche
2caf0 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ma data structur
2cb00 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61  es between [data
2cb10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2cb20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a  | connections].*
2cb30 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  * to the same da
2cb40 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20  tabase. Sharing 
2cb50 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
2cb60 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72  e argument is tr
2cb70 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c  ue.** and disabl
2cb80 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
2cb90 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a  nt is false..**.
2cba0 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67  ** Cache sharing
2cbb0 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
2cbc0 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20  disabled for an 
2cbd0 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a  entire process..
2cbe0 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61  ** This is a cha
2cbf0 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65  nge as of SQLite
2cc00 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20   version 3.5.0. 
2cc10 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e  In prior version
2cc20 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20  s of SQLite,.** 
2cc30 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62  sharing was enab
2cc40 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
2cc50 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20  for each thread 
2cc60 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
2cc70 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72  * The cache shar
2cc80 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20  ing mode set by 
2cc90 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65  this interface e
2cca0 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65  ffects all subse
2ccb0 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
2ccc0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
2ccd0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2cce0 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71  n_v2()], and [sq
2ccf0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
2cd00 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74  .** Existing dat
2cd10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2cd20 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74  s continue use t
2cd30 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a  he sharing mode.
2cd40 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65  ** that was in e
2cd50 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d  ffect at the tim
2cd60 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e  e they were open
2cd70 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ed..**.** Virtua
2cd80 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20  l tables cannot 
2cd90 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73  be used with a s
2cda0 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68  hared cache.  Wh
2cdb0 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  en shared.** cac
2cdc0 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74  he is enabled, t
2cdd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2cde0 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49  te_module()] API
2cdf0 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
2ce00 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  r.** virtual tab
2ce10 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  les will always 
2ce20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
2ce30 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2ce40 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
2ce50 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
2ce60 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62  d cache was enab
2ce70 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
2ce80 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
2ce90 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65    An [error code
2cea0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74  ] is returned ot
2ceb0 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53  herwise..**.** S
2cec0 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
2ced0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
2cee0 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
2cef0 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
2cf00 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
2cf10 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
2cf20 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
2cf30 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
2cf40 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
2cf50 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
2cf60 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
2cf70 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
2cf80 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
2cf90 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52 65 71   Mode].**.** Req
2cfa0 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 33  uirements: [H103
2cfb0 33 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b 48 31  31] [H10336] [H1
2cfc0 30 33 33 37 5d 20 5b 48 31 30 33 33 39 5d 0a 2a  0337] [H10339].*
2cfd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
2cfe0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
2cff0 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e(int);../*.** C
2d000 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74  API3REF: Attempt
2d010 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
2d020 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 3c 53  mory {H17340} <S
2d030 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30220>.**.** The
2d040 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
2d050 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66  _memory() interf
2d060 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
2d070 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20  free N bytes.** 
2d080 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62  of heap memory b
2d090 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e  y deallocating n
2d0a0 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
2d0b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a  ory allocations.
2d0c0 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64  ** held by the d
2d0d0 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e  atabase library.
2d0e0 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75   {END}  Memory u
2d0f0 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
2d100 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
2d110 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
2d120 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
2d130 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
2d140 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
2d150 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2d160 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73  memory() returns
2d170 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2d180 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
2d190 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69  eed,.** which mi
2d1a0 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
2d1b0 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f  ess than the amo
2d1c0 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
2d1d0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
2d1e0 73 3a 20 5b 48 31 37 33 34 31 5d 20 5b 48 31 37  s: [H17341] [H17
2d1f0 33 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  342].*/.int sqli
2d200 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2d210 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ry(int);../*.** 
2d220 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65  CAPI3REF: Impose
2d230 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
2d240 20 53 69 7a 65 20 7b 48 31 37 33 35 30 7d 20 3c   Size {H17350} <
2d250 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30220>.**.** Th
2d260 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  e sqlite3_soft_h
2d270 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65  eap_limit() inte
2d280 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 22  rface places a "
2d290 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f  soft" limit.** o
2d2a0 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  n the amount of 
2d2b0 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74  heap memory that
2d2c0 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65   may be allocate
2d2d0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  d by SQLite..** 
2d2e0 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61  If an internal a
2d2f0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71  llocation is req
2d300 75 65 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c  uested that woul
2d310 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  d exceed the.** 
2d320 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c  soft heap limit,
2d330 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2d340 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69  e_memory()] is i
2d350 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a  nvoked one or.**
2d360 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66   more times to f
2d370 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63  ree up some spac
2d380 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c  e before the all
2d390 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f  ocation is perfo
2d3a0 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rmed..**.** The 
2d3b0 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20  limit is called 
2d3c0 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20  "soft", because 
2d3d0 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  if [sqlite3_rele
2d3e0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a  ase_memory()].**
2d3f0 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66   cannot free suf
2d400 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74  ficient memory t
2d410 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69  o prevent the li
2d420 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65  mit from being e
2d430 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20  xceeded,.** the 
2d440 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
2d450 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74  ted anyway and t
2d460 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  he current opera
2d470 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a  tion proceeds..*
2d480 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20  *.** A negative 
2d490 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f  or zero value fo
2d4a0 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74  r N means that t
2d4b0 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20  here is no soft 
2d4c0 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a  heap limit and.*
2d4d0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
2d4e0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c  se_memory()] wil
2d4f0 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  l only be called
2d500 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20   when memory is 
2d510 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68  exhausted..** Th
2d520 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
2d530 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
2d540 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e  p limit is zero.
2d550 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  .**.** SQLite ma
2d560 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72  kes a best effor
2d570 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73  t to honor the s
2d580 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a  oft heap limit..
2d590 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f  ** But if the so
2d5a0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61  ft heap limit ca
2d5b0 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c  nnot be honored,
2d5c0 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a   execution will.
2d5d0 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68  ** continue with
2d5e0 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74  out error or not
2d5f0 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73  ification.  This
2d600 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69   is why the limi
2d610 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61  t is.** called a
2d620 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20   "soft" limit.  
2d630 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f  It is advisory o
2d640 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  nly..**.** Prior
2d650 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
2d660 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72  on 3.5.0, this r
2d670 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73  outine only cons
2d680 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f  trained the memo
2d690 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20  ry.** allocated 
2d6a0 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
2d6b0 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68  ad - the same th
2d6c0 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68  read in which th
2d6d0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75  is routine.** ru
2d6e0 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77  ns.  Beginning w
2d6f0 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69  ith SQLite versi
2d700 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f  on 3.5.0, the so
2d710 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
2d720 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61  .** applied to a
2d730 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20  ll threads. The 
2d740 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20  value specified 
2d750 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
2d760 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e  p limit.** is an
2d770 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20   upper bound on 
2d780 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79  the total memory
2d790 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
2d7a0 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a  all threads. In.
2d7b0 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  ** version 3.5.0
2d7c0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63   there is no mec
2d7d0 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74  hanism for limit
2d7e0 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61  ing the heap usa
2d7f0 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69  ge for.** indivi
2d800 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a  dual threads..**
2d810 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
2d820 3a 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20 5b 48  :.** [H16351] [H
2d830 31 36 33 35 32 5d 20 5b 48 31 36 33 35 33 5d 20  16352] [H16353] 
2d840 5b 48 31 36 33 35 34 5d 20 5b 48 31 36 33 35 35  [H16354] [H16355
2d850 5d 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a 76 6f  ] [H16358].*/.vo
2d860 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  id sqlite3_soft_
2d870 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b  heap_limit(int);
2d880 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d890 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61  : Extract Metada
2d8a0 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d  ta About A Colum
2d8b0 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b 48 31  n Of A Table {H1
2d8c0 32 38 35 30 7d 20 3c 53 36 30 33 30 30 3e 0a 2a  2850} <S60300>.*
2d8d0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
2d8e0 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61  e returns metada
2d8f0 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69  ta about a speci
2d900 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  fic column of a 
2d910 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61  specific.** data
2d920 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73  base table acces
2d930 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  sible using the 
2d940 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2d950 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
2d960 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
2d970 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  rst function arg
2d980 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
2d990 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74   column is ident
2d9a0 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63  ified by the sec
2d9b0 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66  ond, third and f
2d9c0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
2d9d0 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63   to.** this func
2d9e0 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64  tion. The second
2d9f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69   parameter is ei
2da00 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66  ther the name of
2da10 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
2da20 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22   (i.e. "main", "
2da30 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61  temp" or an atta
2da40 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63  ched database) c
2da50 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70  ontaining the sp
2da60 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65  ecified.** table
2da70 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20   or NULL. If it 
2da80 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c  is NULL, then al
2da90 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  l attached datab
2daa0 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65  ases are searche
2dab0 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62  d.** for the tab
2dac0 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  le using the sam
2dad0 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64  e algorithm used
2dae0 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
2daf0 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65   engine to.** re
2db00 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65  solve unqualifie
2db10 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63  d table referenc
2db20 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  es..**.** The th
2db30 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
2db40 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
2db50 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74  s function are t
2db60 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  he table and col
2db70 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  umn.** name of t
2db80 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
2db90 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
2dba0 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
2dbb0 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  e parameters.** 
2dbc0 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  may be NULL..**.
2dbd0 2a 2a 20 4d 65 74 61 64 61 74 61 20 69 73 20 72  ** Metadata is r
2dbe0 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69  eturned by writi
2dbf0 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  ng to the memory
2dc00 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65   locations passe
2dc10 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20  d as the 5th.** 
2dc20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70  and subsequent p
2dc30 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
2dc40 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20  s function. Any 
2dc50 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e  of these argumen
2dc60 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c  ts may be.** NUL
2dc70 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  L, in which case
2dc80 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2dc90 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65  ng element of me
2dca0 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65  tadata is omitte
2dcb0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d..**.** <blockq
2dcc0 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
2dcd0 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
2dce0 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65  tr><th> Paramete
2dcf0 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72  r <th> Output<br
2dd00 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63  >Type <th>  Desc
2dd10 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  ription.**.** <t
2dd20 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20  r><td> 5th <td> 
2dd30 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
2dd40 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74   Data type.** <t
2dd50 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20  r><td> 6th <td> 
2dd60 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
2dd70 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74   Name of default
2dd80 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2dd90 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nce.** <tr><td> 
2dda0 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  7th <td> int    
2ddb0 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
2ddc0 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e  f column has a N
2ddd0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
2dde0 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38  nt.** <tr><td> 8
2ddf0 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
2de00 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
2de10 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20   column is part 
2de20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  of the PRIMARY K
2de30 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39  EY.** <tr><td> 9
2de40 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
2de50 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
2de60 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f   column is [AUTO
2de70 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f  INCREMENT].** </
2de80 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
2de90 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
2dea0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64  e memory pointed
2deb0 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61   to by the chara
2dec0 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65  cter pointers re
2ded0 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a  turned for the.*
2dee0 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79  * declaration ty
2def0 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e  pe and collation
2df00 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c   sequence is val
2df10 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68  id only until th
2df20 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74  e next.** call t
2df30 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49  o any SQLite API
2df40 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2df50 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65   If the specifie
2df60 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
2df70 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b  lly a view, an [
2df80 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2df90 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
2dfa0 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
2dfb0 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64  column is "rowid
2dfc0 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f  ", "oid" or "_ro
2dfd0 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20  wid_" and an.** 
2dfe0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
2dff0 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73   KEY] column has
2e000 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79   been explicitly
2e010 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20   declared, then 
2e020 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61  the output.** pa
2e030 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
2e040 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69   for the explici
2e050 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
2e060 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73  umn. If there is
2e070 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c   no.** explicitl
2e080 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45  y declared [INTE
2e090 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
2e0a0 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68   column, then th
2e0b0 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
2e0c0 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61  meters are set a
2e0d0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
2e0e0 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61   <pre>.**     da
2e0f0 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45  ta type: "INTEGE
2e100 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74  R".**     collat
2e110 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42  ion sequence: "B
2e120 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f  INARY".**     no
2e130 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20  t null: 0.**    
2e140 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a   primary key: 1.
2e150 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72  **     auto incr
2e160 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72  ement: 0.** </pr
2e170 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  e>.**.** This fu
2e180 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20  nction may load 
2e190 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65  one or more sche
2e1a0 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73  mas from databas
2e1b0 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a  e files. If an.*
2e1c0 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  * error occurs d
2e1d0 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65  uring this proce
2e1e0 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  ss, or if the re
2e1f0 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72  quested table or
2e200 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f   column.** canno
2e210 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b  t be found, an [
2e220 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2e230 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65  eturned and an e
2e240 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66  rror message lef
2e250 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74  t.** in the [dat
2e260 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e270 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76  ] (to be retriev
2e280 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
2e290 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a  _errmsg())..**.*
2e2a0 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e  * This API is on
2e2b0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
2e2c0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
2e2d0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
2e2e0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
2e2f0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
2e300 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
2e310 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
2e320 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
2e330 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
2e340 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69  metadata(.  sqli
2e350 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2e360 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65          /* Conne
2e370 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a  ction handle */.
2e380 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
2e390 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a  bName,        /*
2e3a0 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f   Database name o
2e3b0 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73  r NULL */.  cons
2e3c0 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61  t char *zTableNa
2e3d0 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65  me,     /* Table
2e3e0 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74   name */.  const
2e3f0 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61   char *zColumnNa
2e400 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e  me,    /* Column
2e410 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20   name */.  char 
2e420 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79  const **pzDataTy
2e430 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  pe,    /* OUTPUT
2e440 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20  : Declared data 
2e450 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  type */.  char c
2e460 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71  onst **pzCollSeq
2e470 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  ,     /* OUTPUT:
2e480 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   Collation seque
2e490 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e  nce name */.  in
2e4a0 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20  t *pNotNull,    
2e4b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
2e4c0 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54  PUT: True if NOT
2e4d0 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
2e4e0 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74   exists */.  int
2e4f0 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20   *pPrimaryKey,  
2e500 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2e510 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
2e520 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f  mn part of PK */
2e530 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63  .  int *pAutoinc
2e540 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2e550 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
2e560 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f  f column is auto
2e570 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b  -increment */.);
2e580 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e590 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  : Load An Extens
2e5a0 69 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53 32  ion {H12600} <S2
2e5b0 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0500>.**.** This
2e5c0 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73   interface loads
2e5d0 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e   an SQLite exten
2e5e0 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f  sion library fro
2e5f0 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65  m the named file
2e600 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31 7d  ..**.** {H12601}
2e610 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61   The sqlite3_loa
2e620 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
2e630 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
2e640 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20   to load an.**  
2e650 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 65          SQLite e
2e660 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79  xtension library
2e670 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68   contained in th
2e680 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a  e file zFile..**
2e690 0a 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 68 65  .** {H12602} The
2e6a0 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20   entry point is 
2e6b0 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  zProc..**.** {H1
2e6c0 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20  2603} zProc may 
2e6d0 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63  be 0, in which c
2e6e0 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ase the name of 
2e6f0 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a  the entry point.
2e700 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
2e710 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33  ults to "sqlite3
2e720 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22  _extension_init"
2e730 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34 7d  ..**.** {H12604}
2e740 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61   The sqlite3_loa
2e750 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
2e760 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65  terface shall re
2e770 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
2e780 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
2e790 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
2e7a0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
2e7b0 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
2e7c0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30  ng..**.** {H1260
2e7d0 35 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  5} If an error o
2e7e0 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d  ccurs and pzErrM
2e7f0 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65  sg is not 0, the
2e800 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
2e810 20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f    [sqlite3_load_
2e820 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
2e830 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74  erface shall att
2e840 65 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20  empt to.**      
2e850 20 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d      fill *pzErrM
2e860 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65  sg with error me
2e870 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65  ssage text store
2e880 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  d in memory.**  
2e890 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64          obtained
2e8a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2e8b0 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d 20  alloc()]. {END} 
2e8c0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   The calling fun
2e8d0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
2e8e0 20 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68    should free th
2e8f0 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c  is memory by cal
2e900 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  ling [sqlite3_fr
2e910 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ee()]..**.** {H1
2e920 32 36 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e 20  2606} Extension 
2e930 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20  loading must be 
2e940 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a  enabled using.**
2e950 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2e960 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
2e970 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f  xtension()] prio
2e980 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  r to calling thi
2e990 73 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20 20  s API,.**       
2e9a0 20 20 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20     otherwise an 
2e9b0 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
2e9c0 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  turned..*/.int s
2e9d0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
2e9e0 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  nsion(.  sqlite3
2e9f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
2ea00 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e  * Load the exten
2ea10 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64  sion into this d
2ea20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ea30 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
2ea40 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a  ar *zFile,    /*
2ea50 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61   Name of the sha
2ea60 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  red library cont
2ea70 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e  aining extension
2ea80 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2ea90 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45   *zProc,    /* E
2eaa0 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72  ntry point.  Der
2eab0 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20  ived from zFile 
2eac0 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a  if 0 */.  char *
2ead0 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20  *pzErrMsg       
2eae0 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73  /* Put error mes
2eaf0 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74  sage here if not
2eb00 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   0 */.);../*.** 
2eb10 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
2eb20 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
2eb30 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 48  nsion Loading {H
2eb40 31 32 36 32 30 7d 20 3c 53 32 30 35 30 30 3e 0a  12620} <S20500>.
2eb50 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20  **.** So as not 
2eb60 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79  to open security
2eb70 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20   holes in older 
2eb80 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
2eb90 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61  t are.** unprepa
2eba0 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68  red to deal with
2ebb0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
2ebc0 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61  ng, and as a mea
2ebd0 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a  ns of disabling.
2ebe0 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  ** extension loa
2ebf0 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75  ding while evalu
2ec00 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72  ating user-enter
2ec10 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c  ed SQL, the foll
2ec20 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20  owing API.** is 
2ec30 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e  provided to turn
2ec40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
2ec50 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
2ec60 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64  mechanism on and
2ec70 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65   off..**.** Exte
2ec80 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73  nsion loading is
2ec90 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e   off by default.
2eca0 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36   See ticket #186
2ecb0 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 31  3..**.** {H12621
2ecc0 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74  } Call the sqlit
2ecd0 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
2ece0 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69  xtension() routi
2ecf0 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31  ne with onoff==1
2ed00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
2ed10 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c  turn extension l
2ed20 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61  oading on and ca
2ed30 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66  ll it with onoff
2ed40 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 20  ==0 to turn.**  
2ed50 20 20 20 20 20 20 20 20 69 74 20 62 61 63 6b 20          it back 
2ed60 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a 2a  off again..**.**
2ed70 20 7b 48 31 32 36 32 32 7d 20 45 78 74 65 6e 73   {H12622} Extens
2ed80 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f  ion loading is o
2ed90 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ff by default..*
2eda0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
2edb0 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
2edc0 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ion(sqlite3 *db,
2edd0 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
2ede0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
2edf0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64  tomatically Load
2ee00 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73 20 7b   An Extensions {
2ee10 48 31 32 36 34 30 7d 20 3c 53 32 30 35 30 30 3e  H12640} <S20500>
2ee20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
2ee30 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61  can be invoked a
2ee40 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75  t program startu
2ee50 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65  p in order to re
2ee60 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72  gister.** one or
2ee70 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79   more statically
2ee80 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f   linked extensio
2ee90 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  ns that will be 
2eea0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20  available.** to 
2eeb0 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 61 73  all new [databas
2eec0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20  e connections]. 
2eed0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  {END}.**.** This
2eee0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
2eef0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2ef00 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e   extension in an
2ef10 20 61 72 72 61 79 20 74 68 61 74 20 69 73 0a 2a   array that is.*
2ef20 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
2ef30 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2ef40 29 5d 2e 20 20 49 66 20 79 6f 75 20 72 75 6e 20  )].  If you run 
2ef50 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 63 68  a memory leak ch
2ef60 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75 72  ecker.** on your
2ef70 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20   program and it 
2ef80 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62  reports a leak b
2ef90 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 20 61  ecause of this a
2efa0 72 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a 20  rray, invoke.** 
2efb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61  [sqlite3_reset_a
2efc0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  uto_extension()]
2efd0 20 70 72 69 6f 72 20 74 6f 20 73 68 75 74 64 6f   prior to shutdo
2efe0 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d  wn to free the m
2eff0 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  emory..**.** {H1
2f000 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74  2641} This funct
2f010 69 6f 6e 20 72 65 67 69 73 74 65 72 73 20 61 6e  ion registers an
2f020 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79   extension entry
2f030 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 0a 2a   point that is.*
2f040 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d  *          autom
2f050 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64  atically invoked
2f060 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20   whenever a new 
2f070 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2f080 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20  tion].**        
2f090 20 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e    is opened usin
2f0a0 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  g [sqlite3_open(
2f0b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2f0c0 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  n16()],.**      
2f0d0 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
2f0e0 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  open_v2()]..**.*
2f0f0 2a 20 7b 48 31 32 36 34 32 7d 20 44 75 70 6c 69  * {H12642} Dupli
2f100 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20  cate extensions 
2f110 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20  are detected so 
2f120 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  calling this rou
2f130 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tine.**         
2f140 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
2f150 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78  with the same ex
2f160 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c  tension is harml
2f170 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  ess..**.** {H126
2f180 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65  43} This routine
2f190 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65   stores a pointe
2f1a0 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69  r to the extensi
2f1b0 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a  on in an array.*
2f1c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
2f1d0 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  is obtained from
2f1e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2f1f0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  ()]..**.** {H126
2f200 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65 78  44} Automatic ex
2f210 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61  tensions apply a
2f220 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64  cross all thread
2f230 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2f240 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
2f250 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f  (void (*xEntryPo
2f260 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a  int)(void));../*
2f270 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2f280 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78  set Automatic Ex
2f290 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20  tension Loading 
2f2a0 7b 48 31 32 36 36 30 7d 20 3c 53 32 30 35 30 30  {H12660} <S20500
2f2b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  >.**.** This fun
2f2c0 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61  ction disables a
2f2d0 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ll previously re
2f2e0 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74  gistered automat
2f2f0 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73  ic.** extensions
2f300 2e 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e 64 6f  . {END}  It undo
2f310 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
2f320 20 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b 73   all prior.** [s
2f330 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
2f340 6e 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e 0a  nsion()] calls..
2f350 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d 20 54  **.** {H12661} T
2f360 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  his function dis
2f370 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f  ables all previo
2f380 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 0a  usly registered.
2f390 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f  **          auto
2f3a0 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
2f3b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 32 7d  ..**.** {H12662}
2f3c0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64   This function d
2f3d0 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69  isables automati
2f3e0 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20  c extensions in 
2f3f0 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a  all threads..*/.
2f400 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2f410 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
2f420 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a  n(void);../*.***
2f430 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  *** EXPERIMENTAL
2f440 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68   - subject to ch
2f450 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74  ange without not
2f460 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ice ************
2f470 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  **.**.** The int
2f480 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
2f490 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
2f4a0 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74  anism is current
2f4b0 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  ly considered.**
2f4c0 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e   to be experimen
2f4d0 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66  tal.  The interf
2f4e0 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ace might change
2f4f0 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65   in incompatible
2f500 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69   ways..** If thi
2f510 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66  s is a problem f
2f520 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75  or you, do not u
2f530 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  se the interface
2f540 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a   at this time..*
2f550 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69  *.** When the vi
2f560 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
2f570 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73  anism stabilizes
2f580 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
2f590 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
2f5a0 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
2f5b0 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
2f5c0 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
2f5d0 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a  is comment..*/..
2f5e0 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73  /*.** Structures
2f5f0 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72   used by the vir
2f600 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72  tual table inter
2f610 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20  face.*/.typedef 
2f620 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
2f630 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62  tab sqlite3_vtab
2f640 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
2f650 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
2f660 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  nfo sqlite3_inde
2f670 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20  x_info;.typedef 
2f680 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
2f690 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74  tab_cursor sqlit
2f6a0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a  e3_vtab_cursor;.
2f6b0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2f6c0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71  qlite3_module sq
2f6d0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f  lite3_module;../
2f6e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
2f6f0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a  irtual Table Obj
2f700 65 63 74 20 7b 48 31 38 30 30 30 7d 20 3c 53 32  ect {H18000} <S2
2f710 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0400>.** KEYWORD
2f720 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  S: sqlite3_modul
2f730 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e {virtual table
2f740 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 58 50 45   module}.** EXPE
2f750 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
2f760 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 73  his structure, s
2f770 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20  ometimes called 
2f780 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62  a a "virtual tab
2f790 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20  le module", .** 
2f7a0 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c  defines the impl
2f7b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20  ementation of a 
2f7c0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
2f7d0 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75  .  .** This stru
2f7e0 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d  cture consists m
2f7f0 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73  ostly of methods
2f800 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
2f810 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c  .**.** A virtual
2f820 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73   table module is
2f830 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c   created by fill
2f840 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74  ing in a persist
2f850 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20  ent.** instance 
2f860 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
2f870 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20  e and passing a 
2f880 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2f890 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b  instance.** to [
2f8a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
2f8b0 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c  odule()] or [sql
2f8c0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
2f8d0 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65  le_v2()]..** The
2f8e0 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65   registration re
2f8f0 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69  mains valid unti
2f900 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 64  l it is replaced
2f910 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a   by a different.
2f920 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74  ** module or unt
2f930 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  il the [database
2f940 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f   connection] clo
2f950 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  ses.  The conten
2f960 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72  t.** of this str
2f970 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20  ucture must not 
2f980 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20  change while it 
2f990 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69  is registered wi
2f9a0 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61  th.** any databa
2f9b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a  se connection..*
2f9c0 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
2f9d0 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20  _module {.  int 
2f9e0 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
2f9f0 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74  (*xCreate)(sqlit
2fa00 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
2fa10 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2fa20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
2fa30 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
2fa40 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2fa50 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
2fa60 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
2fa70 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63  .  int (*xConnec
2fa80 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  t)(sqlite3*, voi
2fa90 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
2faa0 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
2fab0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
2fac0 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
2fad0 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
2fae0 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
2faf0 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
2fb00 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c  *xBestIndex)(sql
2fb10 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2fb20 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  , sqlite3_index_
2fb30 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  info*);.  int (*
2fb40 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c  xDisconnect)(sql
2fb50 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2fb60 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74  );.  int (*xDest
2fb70 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61  roy)(sqlite3_vta
2fb80 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2fb90 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
2fba0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73  3_vtab *pVTab, s
2fbb0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2fbc0 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a  or **ppCursor);.
2fbd0 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
2fbe0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2fbf0 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
2fc00 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f  Filter)(sqlite3_
2fc10 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e  vtab_cursor*, in
2fc20 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20  t idxNum, const 
2fc30 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20  char *idxStr,.  
2fc40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
2fc50 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f  t argc, sqlite3_
2fc60 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20  value **argv);. 
2fc70 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71   int (*xNext)(sq
2fc80 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2fc90 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f  r*);.  int (*xEo
2fca0 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  f)(sqlite3_vtab_
2fcb0 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
2fcc0 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74  (*xColumn)(sqlit
2fcd0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
2fce0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2fcf0 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
2fd00 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33  *xRowid)(sqlite3
2fd10 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
2fd20 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52  qlite3_int64 *pR
2fd30 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78  owid);.  int (*x
2fd40 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f  Update)(sqlite3_
2fd50 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c  vtab *, int, sql
2fd60 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73  ite3_value **, s
2fd70 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b  qlite3_int64 *);
2fd80 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29  .  int (*xBegin)
2fd90 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2fda0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
2fdb0 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74  Sync)(sqlite3_vt
2fdc0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2fdd0 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c  t (*xCommit)(sql
2fde0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2fdf0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c  );.  int (*xRoll
2fe00 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74  back)(sqlite3_vt
2fe10 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2fe20 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f  t (*xFindFunctio
2fe30 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
2fe40 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67  *pVtab, int nArg
2fe50 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
2fe60 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20  ame,.           
2fe70 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2fe80 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69   (**pxFunc)(sqli
2fe90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2fea0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2feb0 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  ),.             
2fec0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a            void *
2fed0 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28  *ppArg);.  int (
2fee0 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65  *xRename)(sqlite
2fef0 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63  3_vtab *pVtab, c
2ff00 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29  onst char *zNew)
2ff10 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ;.};../*.** CAPI
2ff20 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
2ff30 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66  ble Indexing Inf
2ff40 6f 72 6d 61 74 69 6f 6e 20 7b 48 31 38 31 30 30  ormation {H18100
2ff50 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45  } <S20400>.** KE
2ff60 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
2ff70 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58  index_info.** EX
2ff80 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
2ff90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64   The sqlite3_ind
2ffa0 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72  ex_info structur
2ffb0 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72  e and its substr
2ffc0 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20  uctures is used 
2ffd0 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72  to.** pass infor
2ffe0 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20  mation into and 
2fff0 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c  receive the repl
30000 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73  y from the [xBes
30010 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f  tIndex].** metho
30020 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20  d of a [virtual 
30030 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
30040 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72  The fields under
30050 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20   **Inputs** are 
30060 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f  the.** inputs to
30070 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20   xBestIndex and 
30080 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20  are read-only.  
30090 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72  xBestIndex inser
300a0 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74  ts its.** result
300b0 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74  s into the **Out
300c0 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a  puts** fields..*
300d0 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72  *.** The aConstr
300e0 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63  aint[] array rec
300f0 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75 73  ords WHERE claus
30100 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66  e constraints of
30110 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a   the form:.**.**
30120 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20   <pre>column OP 
30130 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  expr</pre>.**.**
30140 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20   where OP is =, 
30150 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74  &lt;, &lt;=, &gt
30160 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20 54 68  ;, or &gt;=.  Th
30170 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65  e particular ope
30180 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72  rator is.** stor
30190 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e  ed in aConstrain
301a0 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64  t[].op.  The ind
301b0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
301c0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a   is stored in.**
301d0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69   aConstraint[].i
301e0 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72  Column.  aConstr
301f0 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73  aint[].usable is
30200 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20   TRUE if the.** 
30210 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68  expr on the righ
30220 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20  t-hand side can 
30230 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e  be evaluated (an
30240 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74  d thus the const
30250 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62  raint.** is usab
30260 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66  le) and false if
30270 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a   it cannot..**.*
30280 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20  * The optimizer 
30290 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
302a0 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74  verts terms of t
302b0 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50  he form "expr OP
302c0 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20   column".** and 
302d0 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70  makes other simp
302e0 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74  lifications to t
302f0 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
30300 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f  in an attempt to
30310 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20  .** get as many 
30320 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72  WHERE clause ter
30330 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d  ms into the form
30340 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20   shown above as 
30350 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  possible..** The
30360 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
30370 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74  rray only report
30380 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  s WHERE clause t
30390 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72  erms in the corr
303a0 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74  ect.** form that
303b0 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61   refer to the pa
303c0 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c  rticular virtual
303d0 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65   table being que
303e0 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f  ried..**.** Info
303f0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
30400 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
30410 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  e is stored in a
30420 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61  OrderBy[]..** Ea
30430 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65  ch term of aOrde
30440 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f  rBy records a co
30450 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45  lumn of the ORDE
30460 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a  R BY clause..**.
30470 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64  ** The [xBestInd
30480 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  ex] method must 
30490 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74  fill aConstraint
304a0 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66  Usage[] with inf
304b0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
304c0 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72  t what parameter
304d0 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69  s to pass to xFi
304e0 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e  lter.  If argvIn
304f0 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68  dex>0 then.** th
30500 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64  e right-hand sid
30510 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70  e of the corresp
30520 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69  onding aConstrai
30530 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65  nt[] is evaluate
30540 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73  d.** and becomes
30550 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74   the argvIndex-t
30560 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e  h entry in argv.
30570 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74    If aConstraint
30580 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20  Usage[].omit.** 
30590 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68  is true, then th
305a0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  e constraint is 
305b0 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75  assumed to be fu
305c0 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74  lly handled by t
305d0 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  he.** virtual ta
305e0 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63  ble and is not c
305f0 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20  hecked again by 
30600 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
30610 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78  e idxNum and idx
30620 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72  Ptr values are r
30630 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73  ecorded and pass
30640 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b  ed into the.** [
30650 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e  xFilter] method.
30660 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
30670 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  e()] is used to 
30680 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61  free idxPtr if a
30690 6e 64 20 6f 6e 6c 79 20 69 66 66 0a 2a 2a 20 6e  nd only iff.** n
306a0 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20  eedToFreeIdxPtr 
306b0 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  is true..**.** T
306c0 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d  he orderByConsum
306d0 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75  ed means that ou
306e0 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74  tput from [xFilt
306f0 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c  er]/[xNext] will
30700 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65   occur in.** the
30710 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74   correct order t
30720 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52  o satisfy the OR
30730 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f  DER BY clause so
30740 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74   that no separat
30750 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65  e.** sorting ste
30760 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  p is required..*
30770 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61 74  *.** The estimat
30780 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20  edCost value is 
30790 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74  an estimate of t
307a0 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67  he cost of doing
307b0 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c   the.** particul
307c0 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75  ar lookup.  A fu
307d0 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62  ll scan of a tab
307e0 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65  le with N entrie
307f0 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  s should have.**
30800 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41   a cost of N.  A
30810 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f   binary search o
30820 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65  f a table of N e
30830 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
30840 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20  ve a.** cost of 
30850 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f  approximately lo
30860 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  g(N)..*/.struct 
30870 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
30880 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73  fo {.  /* Inputs
30890 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74   */.  int nConst
308a0 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20  raint;          
308b0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e   /* Number of en
308c0 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72  tries in aConstr
308d0 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74  aint */.  struct
308e0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
308f0 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20  onstraint {.    
30900 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
30910 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
30920 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e  lumn on left-han
30930 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72  d side of constr
30940 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73  aint */.     uns
30950 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20  igned char op;  
30960 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72         /* Constr
30970 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f  aint operator */
30980 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
30990 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20  har usable;     
309a0 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20  /* True if this 
309b0 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73  constraint is us
309c0 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74  able */.     int
309d0 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20   iTermOffset;   
309e0 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69         /* Used i
309f0 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73  nternally - xBes
30a00 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67  tIndex should ig
30a10 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f  nore */.  } *aCo
30a20 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
30a30 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66       /* Table of
30a40 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
30a50 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69  nstraints */.  i
30a60 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20  nt nOrderBy;    
30a70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
30a80 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
30a90 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
30aa0 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  use */.  struct 
30ab0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72  sqlite3_index_or
30ac0 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74  derby {.     int
30ad0 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20   iColumn;       
30ae0 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e         /* Column
30af0 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20   number */.     
30b00 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65  unsigned char de
30b10 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75  sc;       /* Tru
30b20 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c  e for DESC.  Fal
30b30 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20  se for ASC. */. 
30b40 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20   } *aOrderBy;   
30b50 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54              /* T
30b60 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
30b70 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75  se */.  /* Outpu
30b80 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  ts */.  struct s
30b90 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e  qlite3_index_con
30ba0 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a  straint_usage {.
30bb0 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65      int argvInde
30bc0 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  x;           /* 
30bd0 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e  if >0, constrain
30be0 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67  t is part of arg
30bf0 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a  v to xFilter */.
30c00 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
30c10 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20  r omit;      /* 
30c20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65  Do not code a te
30c30 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73  st for this cons
30c40 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61  traint */.  } *a
30c50 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b  ConstraintUsage;
30c60 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20  .  int idxNum;  
30c70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
30c80 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20   Number used to 
30c90 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64  identify the ind
30ca0 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64  ex */.  char *id
30cb0 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20  xStr;           
30cc0 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f     /* String, po
30cd0 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20  ssibly obtained 
30ce0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
30cf0 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65  loc */.  int nee
30d00 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20  dToFreeIdxStr;  
30d10 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53      /* Free idxS
30d20 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  tr using sqlite3
30d30 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20  _free() if true 
30d40 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79  */.  int orderBy
30d50 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20  Consumed;       
30d60 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75  /* True if outpu
30d70 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64  t is already ord
30d80 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65  ered */.  double
30d90 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20   estimatedCost; 
30da0 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65       /* Estimate
30db0 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20  d cost of using 
30dc0 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b  this index */.};
30dd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
30de0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
30df0 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65  _EQ    2.#define
30e00 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
30e10 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34  NSTRAINT_GT    4
30e20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
30e30 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
30e40 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65  _LE    8.#define
30e50 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
30e60 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31  NSTRAINT_LT    1
30e70 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
30e80 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
30e90 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69  T_GE    32.#defi
30ea0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
30eb0 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48  CONSTRAINT_MATCH
30ec0 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   64../*.** CAPI3
30ed0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
30ee0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d  Virtual Table Im
30ef0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31  plementation {H1
30f00 38 32 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a  8200} <S20400>.*
30f10 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
30f20 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
30f30 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 67  e is used to reg
30f40 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72  ister a new [vir
30f50 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
30f60 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 4d 6f 64 75  e] name..** Modu
30f70 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65  le names must be
30f80 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f   registered befo
30f90 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61  re.** creating a
30fa0 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61   new [virtual ta
30fb0 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d  ble] using the m
30fc0 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65  odule, or before
30fd0 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65   using a.** pree
30fe0 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c  xisting [virtual
30ff0 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20   table] for the 
31000 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  module..**.** Th
31010 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73  e module name is
31020 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74   registered on t
31030 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
31040 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
31050 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72  ed.** by the fir
31060 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  st parameter.  T
31070 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
31080 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20 62  odule is given b
31090 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64  y the .** second
310a0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
310b0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
310c0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
310d0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
310e0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76  tation of the [v
310f0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
31100 75 6c 65 5d 2e 20 20 20 54 68 65 20 66 6f 75 72  ule].   The four
31110 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  th.** parameter 
31120 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
31130 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e  client data poin
31140 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73  ter that is pass
31150 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e  ed through.** in
31160 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74 65 5d  to the [xCreate]
31170 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20   and [xConnect] 
31180 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 76  methods of the v
31190 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
311a0 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65  ule.** when a ne
311b0 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  w virtual table 
311c0 69 73 20 62 65 20 62 65 69 6e 67 20 63 72 65 61  is be being crea
311d0 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69 61 6c  ted or reinitial
311e0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ized..**.** This
311f0 20 69 6e 74 65 72 66 61 63 65 20 68 61 73 20 65   interface has e
31200 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
31210 65 66 66 65 63 74 20 61 73 20 63 61 6c 6c 69 6e  effect as callin
31220 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
31230 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
31240 5d 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 63 6c  ] with a NULL cl
31250 69 65 6e 74 20 64 61 74 61 20 64 65 73 74 72 75  ient data destru
31260 63 74 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ctor..*/.SQLITE_
31270 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74  EXPERIMENTAL int
31280 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31290 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65  module(.  sqlite
312a0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
312b0 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63       /* SQLite c
312c0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67  onnection to reg
312d0 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74  ister module wit
312e0 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  h */.  const cha
312f0 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20  r *zName,       
31300 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
31310 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e   module */.  con
31320 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
31330 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f  e *p,   /* Metho
31340 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
31350 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c  e */.  void *pCl
31360 69 65 6e 74 44 61 74 61 20 20 20 20 20 20 20 20  ientData        
31370 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61    /* Client data
31380 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f   for xCreate/xCo
31390 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  nnect */.);../*.
313a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
313b0 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20  ister A Virtual 
313c0 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61  Table Implementa
313d0 74 69 6f 6e 20 7b 48 31 38 32 31 30 7d 20 3c 53  tion {H18210} <S
313e0 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  20400>.** EXPERI
313f0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69  MENTAL.**.** Thi
31400 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65  s routine is ide
31410 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 5b 73  ntical to the [s
31420 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
31430 64 75 6c 65 28 29 5d 20 6d 65 74 68 6f 64 2c 0a  dule()] method,.
31440 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
31450 74 20 68 61 73 20 61 6e 20 65 78 74 72 61 20 70  t has an extra p
31460 61 72 61 6d 65 74 65 72 20 74 6f 20 73 70 65 63  arameter to spec
31470 69 66 79 20 0a 2a 2a 20 61 20 64 65 73 74 72 75  ify .** a destru
31480 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f  ctor function fo
31490 72 20 74 68 65 20 63 6c 69 65 6e 74 20 64 61 74  r the client dat
314a0 61 20 70 6f 69 6e 74 65 72 2e 20 20 53 51 4c 69  a pointer.  SQLi
314b0 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b  te will.** invok
314c0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
314d0 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74   function (if it
314e0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68   is not NULL) wh
314f0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20  en SQLite.** no 
31500 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65  longer needs the
31510 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69   pClientData poi
31520 6e 74 65 72 2e 20 20 0a 2a 2f 0a 53 51 4c 49 54  nter.  .*/.SQLIT
31530 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
31540 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
31550 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73  e_module_v2(.  s
31560 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
31570 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
31580 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
31590 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
315a0 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
315b0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
315c0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
315d0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
315e0 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
315f0 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
31600 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
31610 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
31620 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20   *pClientData,  
31630 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
31640 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
31650 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20  e/xConnect */.  
31660 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
31670 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f  void*)     /* Mo
31680 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20  dule destructor 
31690 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a  function */.);..
316a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
316b0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e  Virtual Table In
316c0 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 7b 48  stance Object {H
316d0 31 38 30 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a  18010} <S20400>.
316e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
316f0 69 74 65 33 5f 76 74 61 62 0a 2a 2a 20 45 58 50  ite3_vtab.** EXP
31700 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
31710 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74  Every [virtual t
31720 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70  able module] imp
31730 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
31740 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f   a subclass.** o
31750 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
31760 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 73  structure to des
31770 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c  cribe a particul
31780 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f  ar instance.** o
31790 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74  f the [virtual t
317a0 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62  able].  Each sub
317b0 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65  class will.** be
317c0 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65   tailored to the
317d0 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
317e0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d  of the module im
317f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a  plementation..**
31800 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20   The purpose of 
31810 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20  this superclass 
31820 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72  is to define cer
31830 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74  tain fields that
31840 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74   are.** common t
31850 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70  o all module imp
31860 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a  lementations..**
31870 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c  .** Virtual tabl
31880 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73  es methods can s
31890 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  et an error mess
318a0 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67  age by assigning
318b0 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74   a.** string obt
318c0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
318d0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74  te3_mprintf()] t
318e0 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20  o zErrMsg.  The 
318f0 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a  method should.**
31900 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20   take care that 
31910 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67  any prior string
31920 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63   is freed by a c
31930 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
31940 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72  free()].** prior
31950 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20   to assigning a 
31960 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45  new string to zE
31970 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 68  rrMsg.  After th
31980 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a  e error message.
31990 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20  ** is delivered 
319a0 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74  up to the client
319b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
319c0 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
319d0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
319e0 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74  * freed by sqlit
319f0 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68  e3_free() and th
31a00 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20  e zErrMsg field 
31a10 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a  will be zeroed..
31a20 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
31a30 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74  3_vtab {.  const
31a40 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
31a50 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68  *pModule;  /* Th
31a60 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69  e module for thi
31a70 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  s virtual table 
31a80 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20  */.  int nRef;  
31a90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31aa0 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45       /* NO LONGE
31ab0 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61 72  R USED */.  char
31ac0 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20   *zErrMsg;      
31ad0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
31ae0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f  rror message fro
31af0 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  m sqlite3_mprint
31b00 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74  f() */.  /* Virt
31b10 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
31b20 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74  entations will t
31b30 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64  ypically add add
31b40 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a  itional fields *
31b50 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
31b60 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
31b70 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63  ble Cursor Objec
31b80 74 20 20 7b 48 31 38 30 32 30 7d 20 3c 53 32 30  t  {H18020} <S20
31b90 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  400>.** KEYWORDS
31ba0 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  : sqlite3_vtab_c
31bb0 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74  ursor {virtual t
31bc0 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 20  able cursor}.** 
31bd0 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
31be0 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61  ** Every [virtua
31bf0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
31c00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
31c10 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ses a subclass o
31c20 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  f the.** followi
31c30 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  ng structure to 
31c40 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73  describe cursors
31c50 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f   that point into
31c60 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   the.** [virtual
31c70 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20   table] and are 
31c80 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20  used.** to loop 
31c90 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74  through the virt
31ca0 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73  ual table.  Curs
31cb0 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20  ors are created 
31cc0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
31cd0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70  lite3_module.xOp
31ce0 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68  en | xOpen] meth
31cf0 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  od of the module
31d00 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79   and are destroy
31d10 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71  ed.** by the [sq
31d20 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c  lite3_module.xCl
31d30 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65  ose | xClose] me
31d40 74 68 6f 64 2e 20 20 43 75 73 73 6f 72 73 20 61  thod.  Cussors a
31d50 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  re used.** by th
31d60 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e  e [xFilter], [xN
31d70 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78  ext], [xEof], [x
31d80 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52  Column], and [xR
31d90 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a  owid] methods.**
31da0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20   of the module. 
31db0 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70   Each module imp
31dc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
31dd0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63   define.** the c
31de0 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73  ontent of a curs
31df0 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  or structure to 
31e00 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65  suit its own nee
31e10 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  ds..**.** This s
31e20 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73  uperclass exists
31e30 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66   in order to def
31e40 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68  ine fields of th
31e50 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a  e cursor that.**
31e60 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61   are common to a
31e70 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ll implementatio
31e80 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ns..*/.struct sq
31e90 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
31ea0 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74  r {.  sqlite3_vt
31eb0 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20  ab *pVtab;      
31ec0 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
31ed0 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20   of this cursor 
31ee0 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20  */.  /* Virtual 
31ef0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
31f00 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63  tions will typic
31f10 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f  ally add additio
31f20 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b  nal fields */.};
31f30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31f40 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53 63  : Declare The Sc
31f50 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61  hema Of A Virtua
31f60 6c 20 54 61 62 6c 65 20 7b 48 31 38 32 38 30 7d  l Table {H18280}
31f70 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50   <S20400>.** EXP
31f80 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
31f90 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e  The [xCreate] an
31fa0 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74  d [xConnect] met
31fb0 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69  hods of a.** [vi
31fc0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
31fd0 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 6e  le] call this in
31fe0 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65  terface.** to de
31ff0 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74  clare the format
32000 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20   (the names and 
32010 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65  datatypes of the
32020 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20   columns) of.** 
32030 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
32040 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e  es they implemen
32050 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  t..*/.SQLITE_EXP
32060 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71  ERIMENTAL int sq
32070 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74  lite3_declare_vt
32080 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  ab(sqlite3*, con
32090 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a  st char *zSQL);.
320a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
320b0 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63   Overload A Func
320c0 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75  tion For A Virtu
320d0 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 33 30 30  al Table {H18300
320e0 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58  } <S20400>.** EX
320f0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
32100 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
32110 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65  can provide alte
32120 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e  rnative implemen
32130 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74  tations of funct
32140 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68  ions.** using th
32150 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e  e [xFindFunction
32160 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
32170 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
32180 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74  odule].  .** But
32190 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73   global versions
321a0 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69   of those functi
321b0 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73  ons.** must exis
321c0 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65  t in order to be
321d0 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a   overloaded..**.
321e0 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b 65  ** This API make
321f0 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20  s sure a global 
32200 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e  version of a fun
32210 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72  ction with a par
32220 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20  ticular.** name 
32230 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  and number of pa
32240 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e  rameters exists.
32250 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e    If no such fun
32260 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20  ction exists.** 
32270 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20  before this API 
32280 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77  is called, a new
32290 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65   function is cre
322a0 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65  ated.  The imple
322b0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
322c0 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  the new function
322d0 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 61   always causes a
322e0 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62  n exception to b
322f0 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a  e thrown.  So.**
32300 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f   the new functio
32310 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f  n is not good fo
32320 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74  r anything by it
32330 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a  self.  Its only.
32340 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f  ** purpose is to
32350 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 65   be a placeholde
32360 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  r function that 
32370 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  can be overloade
32380 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 74 75  d.** by a [virtu
32390 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 53 51  al table]..*/.SQ
323a0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
323b0 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76  L int sqlite3_ov
323c0 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28  erload_function(
323d0 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
323e0 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c  char *zFuncName,
323f0 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a   int nArg);../*.
32400 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  ** The interface
32410 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d   to the virtual-
32420 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
32430 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62  defined above (b
32440 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63  ack up.** to a c
32450 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c  omment remarkabl
32460 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69  y similar to thi
32470 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e  s one) is curren
32480 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
32490 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
324a0 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
324b0 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
324c0 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
324d0 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
324e0 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
324f0 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
32500 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
32510 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
32520 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
32530 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
32540 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65  hanism stabilize
32550 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
32560 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
32570 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
32580 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
32590 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
325a0 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a  his comment..**.
325b0 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  ****** EXPERIMEN
325c0 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f  TAL - subject to
325d0 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20   change without 
325e0 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  notice *********
325f0 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  *****.*/../*.** 
32600 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64  CAPI3REF: A Hand
32610 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c  le To An Open BL
32620 4f 42 20 7b 48 31 37 38 30 30 7d 20 3c 53 33 30  OB {H17800} <S30
32630 32 33 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  230>.** KEYWORDS
32640 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20  : {BLOB handle} 
32650 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a  {BLOB handles}.*
32660 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
32670 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
32680 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
32690 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68  en BLOB on which
326a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
326b0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
326c0 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63  ntal BLOB I/O] c
326d0 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e  an be performed.
326e0 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20 74  .** Objects of t
326f0 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65  his type are cre
32700 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
32710 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  _blob_open()].**
32720 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62   and destroyed b
32730 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
32740 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  close()]..** The
32750 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
32760 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
32770 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
32780 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
32790 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
327a0 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61  ead or write sma
327b0 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f  ll subsections o
327c0 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 54  f the BLOB..** T
327d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
327e0 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
327f0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
32800 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  size of the BLOB
32810 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79   in bytes..*/.ty
32820 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
32830 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65  ite3_blob sqlite
32840 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_blob;../*.** C
32850 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20  API3REF: Open A 
32860 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65  BLOB For Increme
32870 6e 74 61 6c 20 49 2f 4f 20 7b 48 31 37 38 31 30  ntal I/O {H17810
32880 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a  } <S30230>.**.**
32890 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 73   This interfaces
328a0 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68   opens a [BLOB h
328b0 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20  andle | handle] 
328c0 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61  to the BLOB loca
328d0 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52  ted.** in row iR
328e0 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75  ow, column zColu
328f0 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65  mn, table zTable
32900 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62   in database zDb
32910 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f  ;.** in other wo
32920 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c  rds, the same BL
32930 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65  OB that would be
32940 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a   selected by:.**
32950 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  .** <pre>.**    
32960 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20   SELECT zColumn 
32970 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20  FROM zDb.zTable 
32980 57 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20  WHERE [rowid] = 
32990 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 20  iRow;.** </pre> 
329a0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74  {END}.**.** If t
329b0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
329c0 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  er is non-zero, 
329d0 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73  then the BLOB is
329e0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
329f0 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61 63  .** and write ac
32a00 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20 7a  cess. If it is z
32a10 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69 73  ero, the BLOB is
32a20 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
32a30 20 61 63 63 65 73 73 2e 0a 2a 2a 20 49 74 20 69   access..** It i
32a40 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
32a50 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20  o open a column 
32a60 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 20  that is part of 
32a70 61 6e 20 69 6e 64 65 78 20 6f 72 20 70 72 69 6d  an index or prim
32a80 61 72 79 20 0a 2a 2a 20 6b 65 79 20 66 6f 72 20  ary .** key for 
32a90 77 72 69 74 69 6e 67 2e 20 5e 49 66 20 5b 66 6f  writing. ^If [fo
32aa0 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
32ab0 61 69 6e 74 73 5d 20 61 72 65 20 65 6e 61 62 6c  aints] are enabl
32ac0 65 64 2c 20 69 74 20 69 73 20 0a 2a 2a 20 6e 6f  ed, it is .** no
32ad0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70  t possible to op
32ae0 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74  en a column that
32af0 20 69 73 20 70 61 72 74 20 6f 66 20 61 20 5b 63   is part of a [c
32b00 68 69 6c 64 20 6b 65 79 5d 20 66 6f 72 20 77 72  hild key] for wr
32b10 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  iting..**.** Not
32b20 65 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  e that the datab
32b30 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20  ase name is not 
32b40 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 61  the filename tha
32b50 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  t contains.** th
32b60 65 20 64 61 74 61 62 61 73 65 20 62 75 74 20 72  e database but r
32b70 61 74 68 65 72 20 74 68 65 20 73 79 6d 62 6f 6c  ather the symbol
32b80 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ic name of the d
32b90 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a 2a 20  atabase that.** 
32ba0 69 73 20 61 73 73 69 67 6e 65 64 20 77 68 65 6e  is assigned when
32bb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
32bc0 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67   connected using
32bd0 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 46 6f   [ATTACH]..** Fo
32be0 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  r the main datab
32bf0 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61  ase file, the da
32c00 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22  tabase name is "
32c10 6d 61 69 6e 22 2e 0a 2a 2a 20 46 6f 72 20 54 45  main"..** For TE
32c20 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64  MP tables, the d
32c30 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20  atabase name is 
32c40 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  "temp"..**.** On
32c50 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
32c60 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
32c70 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42  d and the new [B
32c80 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77  LOB handle] is w
32c90 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70  ritten.** to *pp
32ca0 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20  Blob. Otherwise 
32cb0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
32cc0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
32cd0 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a  *ppBlob is set.*
32ce0 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70  * to be a null p
32cf0 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 69 73 20  ointer..** This 
32d00 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68  function sets th
32d10 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
32d20 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f  ection] error co
32d30 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a  de and message.*
32d40 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61  * accessible via
32d50 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
32d60 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
32d70 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20  3_errmsg()] and 
32d80 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74  related.** funct
32d90 69 6f 6e 73 2e 20 20 4e 6f 74 65 20 74 68 61 74  ions.  Note that
32da0 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 72   the *ppBlob var
32db0 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73 20  iable is always 
32dc0 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 61  initialized in a
32dd0 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61 6b  .** way that mak
32de0 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 69 6e  es it safe to in
32df0 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c  voke [sqlite3_bl
32e00 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a  ob_close()] on *
32e10 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64  ppBlob.** regard
32e20 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
32e30 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  ess or failure o
32e40 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a  f this routine..
32e50 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 6f 77  **.** If the row
32e60 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e   that a BLOB han
32e70 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73  dle points to is
32e80 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a   modified by an.
32e90 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45  ** [UPDATE], [DE
32ea0 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e  LETE], or by [ON
32eb0 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d   CONFLICT] side-
32ec0 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20  effects.** then 
32ed0 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20  the BLOB handle 
32ee0 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78  is marked as "ex
32ef0 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20  pired"..** This 
32f00 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20 63  is true if any c
32f10 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77  olumn of the row
32f20 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65   is changed, eve
32f30 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74  n a column.** ot
32f40 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  her than the one
32f50 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65   the BLOB handle
32f60 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a 2a 20   is open on..** 
32f70 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
32f80 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
32f90 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
32fa0 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a  _write()] for.**
32fb0 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f 42 20   a expired BLOB 
32fc0 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74 68  handle fail with
32fd0 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 65 20   an return code 
32fe0 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  of [SQLITE_ABORT
32ff0 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 20 77 72  ]..** Changes wr
33000 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f  itten into a BLO
33010 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 42  B prior to the B
33020 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61 72 65  LOB expiring are
33030 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b   not.** rollback
33040 20 62 79 20 74 68 65 20 65 78 70 69 72 61 74 69   by the expirati
33050 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20  on of the BLOB. 
33060 20 53 75 63 68 20 63 68 61 6e 67 65 73 20 77 69   Such changes wi
33070 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a  ll eventually.**
33080 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74   commit if the t
33090 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69  ransaction conti
330a0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
330b0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 73 65 20 74 68  on..**.** Use th
330c0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
330d0 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
330e0 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ce to determine 
330f0 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74  the size of.** t
33100 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20  he opened blob. 
33110 20 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62   The size of a b
33120 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 63  lob may not be c
33130 68 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a 2a  hanged by this.*
33140 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55 73  * interface.  Us
33150 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20 53  e the [UPDATE] S
33160 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68  QL command to ch
33170 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66  ange the size of
33180 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a   a.** blob..**.*
33190 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * The [sqlite3_b
331a0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20  ind_zeroblob()] 
331b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
331c0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20  ult_zeroblob()] 
331d0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e  interfaces.** an
331e0 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b  d the built-in [
331f0 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75  zeroblob] SQL fu
33200 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  nction can be us
33210 65 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c 0a  ed, if desired,.
33220 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20  ** to create an 
33230 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c  empty, zero-fill
33240 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 68  ed blob in which
33250 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
33260 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20  e using.** this 
33270 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
33280 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73 6f   To avoid a reso
33290 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 79  urce leak, every
332a0 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
332b0 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e 74  le] should event
332c0 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65  ually.** be rele
332d0 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  ased by a call t
332e0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
332f0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
33300 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
33310 20 5b 48 31 37 38 31 33 5d 20 5b 48 31 37 38 31   [H17813] [H1781
33320 34 5d 20 5b 48 31 37 38 31 36 5d 20 5b 48 31 37  4] [H17816] [H17
33330 38 31 39 5d 20 5b 48 31 37 38 32 31 5d 20 5b 48  819] [H17821] [H
33340 31 37 38 32 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71  17824].*/.int sq
33350 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
33360 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63  .  sqlite3*,.  c
33370 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a  onst char *zDb,.
33380 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
33390 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68  able,.  const ch
333a0 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73  ar *zColumn,.  s
333b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f  qlite3_int64 iRo
333c0 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a  w,.  int flags,.
333d0 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a    sqlite3_blob *
333e0 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a  *ppBlob.);../*.*
333f0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73  * CAPI3REF: Clos
33400 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 20  e A BLOB Handle 
33410 7b 48 31 37 38 33 30 7d 20 3c 53 33 30 32 33 30  {H17830} <S30230
33420 3e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 73 20 61  >.**.** Closes a
33430 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e  n open [BLOB han
33440 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73  dle]..**.** Clos
33450 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c  ing a BLOB shall
33460 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72 65   cause the curre
33470 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  nt transaction t
33480 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74  o commit.** if t
33490 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65  here are no othe
334a0 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64  r BLOBs, no pend
334b0 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74 61  ing prepared sta
334c0 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65  tements, and the
334d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
334e0 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b 61  nection is in [a
334f0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e  utocommit mode].
33500 0a 2a 2a 20 49 66 20 61 6e 79 20 77 72 69 74 65  .** If any write
33510 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f 20 74  s were made to t
33520 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69  he BLOB, they mi
33530 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e 20 63  ght be held in c
33540 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68  ache.** until th
33550 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f  e close operatio
33560 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c 20 66  n if they will f
33570 69 74 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e  it..**.** Closin
33580 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e  g the BLOB often
33590 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e   forces the chan
335a0 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69  ges.** out to di
335b0 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79  sk and so if any
335c0 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75   I/O errors occu
335d0 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b  r, they will lik
335e0 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20  ely occur.** at 
335f0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68  the time when th
33600 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64  e BLOB is closed
33610 2e 20 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68  .  Any errors th
33620 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a  at occur during.
33630 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72  ** closing are r
33640 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e  eported as a non
33650 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c  -zero return val
33660 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 42 4c  ue..**.** The BL
33670 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75 6e 63  OB is closed unc
33680 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45  onditionally.  E
33690 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f 75 74  ven if this rout
336a0 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ine returns.** a
336b0 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 68  n error code, th
336c0 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20  e BLOB is still 
336d0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 43 61  closed..**.** Ca
336e0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
336f0 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70  ne with a null p
33700 6f 69 6e 74 65 72 20 28 77 68 69 63 68 20 61 73  ointer (which as
33710 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e   would be return
33720 65 64 0a 2a 2a 20 62 79 20 66 61 69 6c 65 64 20  ed.** by failed 
33730 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
33740 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69  _blob_open()]) i
33750 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
33760 6f 70 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  op..**.** Requir
33770 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38  ements:.** [H178
33780 33 33 5d 20 5b 48 31 37 38 33 36 5d 20 5b 48 31  33] [H17836] [H1
33790 37 38 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  7839].*/.int sql
337a0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
337b0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b  sqlite3_blob *);
337c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
337d0 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a  : Return The Siz
337e0 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f  e Of An Open BLO
337f0 42 20 7b 48 31 37 38 34 30 7d 20 3c 53 33 30 32  B {H17840} <S302
33800 33 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  30>.**.** Return
33810 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79  s the size in by
33820 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  tes of the BLOB 
33830 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 74  accessible via t
33840 68 65 20 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  he .** successfu
33850 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42  lly opened [BLOB
33860 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20   handle] in its 
33870 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 20  only argument.  
33880 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74  The.** increment
33890 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74  al blob I/O rout
338a0 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65  ines can only re
338b0 61 64 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e  ad or overwritin
338c0 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c  g existing.** bl
338d0 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79  ob content; they
338e0 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
338f0 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f  he size of a blo
33900 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  b..**.** This ro
33910 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73  utine only works
33920 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64   on a [BLOB hand
33930 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65  le] which has be
33940 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79  en created.** by
33950 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73   a prior success
33960 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
33970 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
33980 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20  ] and which has 
33990 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73  not.** been clos
339a0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62  ed by [sqlite3_b
339b0 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50  lob_close()].  P
339c0 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  assing any other
339d0 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74   pointer in.** t
339e0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  o this routine r
339f0 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
33a00 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
33a10 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
33a20 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  avior..**.** Req
33a30 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
33a40 31 37 38 34 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71  17843].*/.int sq
33a50 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
33a60 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
33a70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33a80 46 3a 20 52 65 61 64 20 44 61 74 61 20 46 72 6f  F: Read Data Fro
33a90 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  m A BLOB Increme
33aa0 6e 74 61 6c 6c 79 20 7b 48 31 37 38 35 30 7d 20  ntally {H17850} 
33ab0 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30230>.**.** T
33ac0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
33ad0 75 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74  used to read dat
33ae0 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b  a from an open [
33af0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74  BLOB handle] int
33b00 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75  o a.** caller-su
33b10 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e  pplied buffer. N
33b20 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61   bytes of data a
33b30 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62  re copied into b
33b40 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20  uffer Z.** from 
33b50 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73  the open BLOB, s
33b60 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65  tarting at offse
33b70 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a  t iOffset..**.**
33b80 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73   If offset iOffs
33b90 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  et is less than 
33ba0 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65  N bytes from the
33bb0 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42   end of the BLOB
33bc0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  ,.** [SQLITE_ERR
33bd0 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
33be0 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72  and no data is r
33bf0 65 61 64 2e 20 20 49 66 20 4e 20 6f 72 20 69 4f  ead.  If N or iO
33c00 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73  ffset is.** less
33c10 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c   than zero, [SQL
33c20 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
33c30 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
33c40 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 20 54  ta is read..** T
33c50 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
33c60 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 65 20 74  lob (and hence t
33c70 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65  he maximum value
33c80 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a   of N+iOffset).*
33c90 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
33ca0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73  ned using the [s
33cb0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
33cc0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  s()] interface..
33cd0 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d 70 74  **.** An attempt
33ce0 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 61 6e   to read from an
33cf0 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68   expired [BLOB h
33d00 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74  andle] fails wit
33d10 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f  h an.** error co
33d20 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42  de of [SQLITE_AB
33d30 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73  ORT]..**.** On s
33d40 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f  uccess, SQLITE_O
33d50 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  K is returned..*
33d60 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20  * Otherwise, an 
33d70 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
33d80 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  an [extended err
33d90 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
33da0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  rned..**.** This
33db0 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f   routine only wo
33dc0 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68  rks on a [BLOB h
33dd0 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73  andle] which has
33de0 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a   been created.**
33df0 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63   by a prior succ
33e00 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
33e10 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
33e20 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68  n()] and which h
33e30 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63  as not.** been c
33e40 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  losed by [sqlite
33e50 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
33e60 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74    Passing any ot
33e70 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a  her pointer in.*
33e80 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  * to this routin
33e90 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  e results in und
33ea0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
33eb0 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20  bly undesirable 
33ec0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
33ed0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
33ee0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d  e3_blob_write()]
33ef0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
33f00 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 35 33  ents:.** [H17853
33f10 5d 20 5b 48 31 37 38 35 36 5d 20 5b 48 31 37 38  ] [H17856] [H178
33f20 35 39 5d 20 5b 48 31 37 38 36 32 5d 20 5b 48 31  59] [H17862] [H1
33f30 37 38 36 33 5d 20 5b 48 31 37 38 36 35 5d 20 5b  7863] [H17865] [
33f40 48 31 37 38 36 38 5d 0a 2a 2f 0a 69 6e 74 20 73  H17868].*/.int s
33f50 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
33f60 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
33f70 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c   void *Z, int N,
33f80 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a   int iOffset);..
33f90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33fa0 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20  Write Data Into 
33fb0 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
33fc0 61 6c 6c 79 20 7b 48 31 37 38 37 30 7d 20 3c 53  ally {H17870} <S
33fd0 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  30230>.**.** Thi
33fe0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
33ff0 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 61  ed to write data
34000 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42   into an open [B
34010 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d  LOB handle] from
34020 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70   a.** caller-sup
34030 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20  plied buffer. N 
34040 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
34050 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68  e copied from th
34060 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e  e buffer Z.** in
34070 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42  to the open BLOB
34080 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66  , starting at of
34090 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a  fset iOffset..**
340a0 0a 2a 2a 20 49 66 20 74 68 65 20 5b 42 4c 4f 42  .** If the [BLOB
340b0 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20   handle] passed 
340c0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
340d0 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f 70  ument was not op
340e0 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69 74  ened for.** writ
340f0 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20 70  ing (the flags p
34100 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
34110 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
34120 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a 20  ] was zero),.** 
34130 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
34140 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45  turns [SQLITE_RE
34150 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54  ADONLY]..**.** T
34160 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
34170 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65   only modify the
34180 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65   contents of the
34190 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a 2a 20   BLOB; it is.** 
341a0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
341b0 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69 7a  increase the siz
341c0 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73 69 6e  e of a BLOB usin
341d0 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20 49  g this API..** I
341e0 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  f offset iOffset
341f0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20   is less than N 
34200 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65  bytes from the e
34210 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a  nd of the BLOB,.
34220 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
34230 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
34240 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69  d no data is wri
34250 74 74 65 6e 2e 20 20 49 66 20 4e 20 69 73 0a 2a  tten.  If N is.*
34260 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  * less than zero
34270 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
34280 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
34290 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74  no data is writt
342a0 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20  en..** The size 
342b0 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 61 6e 64  of the BLOB (and
342c0 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d   hence the maxim
342d0 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f  um value of N+iO
342e0 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65  ffset).** can be
342f0 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
34300 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  g the [sqlite3_b
34310 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74  lob_bytes()] int
34320 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 41 6e  erface..**.** An
34330 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74   attempt to writ
34340 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65 64 20  e to an expired 
34350 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61  [BLOB handle] fa
34360 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65  ils with an.** e
34370 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
34380 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20 57 72  LITE_ABORT].  Wr
34390 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42  ites to the BLOB
343a0 20 74 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a   that occurred.*
343b0 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c  * before the [BL
343c0 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72  OB handle] expir
343d0 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65  ed are not rolle
343e0 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a  d back by the.**
343f0 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74   expiration of t
34400 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67  he handle, thoug
34410 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73  h of course thos
34420 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a  e changes might.
34430 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65  ** have been ove
34440 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
34450 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65  statement that e
34460 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20  xpired the BLOB 
34470 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20  handle.** or by 
34480 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e  other independen
34490 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  t statements..**
344a0 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
344b0 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74  SQLITE_OK is ret
344c0 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77  urned..** Otherw
344d0 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72 20  ise, an  [error 
344e0 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74  code] or an [ext
344f0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
34500 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
34510 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
34520 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20  e only works on 
34530 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  a [BLOB handle] 
34540 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63  which has been c
34550 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70  reated.** by a p
34560 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
34570 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
34580 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e  _blob_open()] an
34590 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a  d which has not.
345a0 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62  ** been closed b
345b0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
345c0 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69  close()].  Passi
345d0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69  ng any other poi
345e0 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68  nter in.** to th
345f0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c  is routine resul
34600 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
34610 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
34620 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
34630 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
34640 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  o: [sqlite3_blob
34650 5f 72 65 61 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _read()]..**.** 
34660 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
34670 20 5b 48 31 37 38 37 33 5d 20 5b 48 31 37 38 37   [H17873] [H1787
34680 34 5d 20 5b 48 31 37 38 37 35 5d 20 5b 48 31 37  4] [H17875] [H17
34690 38 37 36 5d 20 5b 48 31 37 38 37 37 5d 20 5b 48  876] [H17877] [H
346a0 31 37 38 37 39 5d 20 5b 48 31 37 38 38 32 5d 20  17879] [H17882] 
346b0 5b 48 31 37 38 38 35 5d 0a 2a 2a 20 5b 48 31 37  [H17885].** [H17
346c0 38 38 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  888].*/.int sqli
346d0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73  te3_blob_write(s
346e0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63  qlite3_blob *, c
346f0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e  onst void *z, in
34700 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74  t n, int iOffset
34710 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34720 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69 6c 65  EF: Virtual File
34730 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 20   System Objects 
34740 7b 48 31 31 32 30 30 7d 20 3c 53 32 30 31 30 30  {H11200} <S20100
34750 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61  >.**.** A virtua
34760 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46  l filesystem (VF
34770 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65  S) is an [sqlite
34780 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a  3_vfs] object.**
34790 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65   that SQLite use
347a0 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a  s to interact.**
347b0 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c   with the underl
347c0 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
347d0 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c  ystem.  Most SQL
347e0 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20  ite builds come 
347f0 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  with a.** single
34800 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68 61   default VFS tha
34810 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65  t is appropriate
34820 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f   for the host co
34830 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56  mputer..** New V
34840 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67 69  FSes can be regi
34850 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73 74  stered and exist
34860 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62 65  ing VFSes can be
34870 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a   unregistered..*
34880 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
34890 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
348a0 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  rovided..**.** T
348b0 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  he sqlite3_vfs_f
348c0 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65 20  ind() interface 
348d0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
348e0 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65 6e  r to a VFS given
348f0 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 4e 61   its name..** Na
34900 6d 65 73 20 61 72 65 20 63 61 73 65 20 73 65 6e  mes are case sen
34910 73 69 74 69 76 65 2e 0a 2a 2a 20 4e 61 6d 65 73  sitive..** Names
34920 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
34930 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
34940 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  gs..** If there 
34950 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20 4e  is no match, a N
34960 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
34970 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 7a  eturned..** If z
34980 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20  VfsName is NULL 
34990 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
349a0 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65 64   VFS is returned
349b0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53 65  ..**.** New VFSe
349c0 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  s are registered
349d0 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76 66   with sqlite3_vf
349e0 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a  s_register()..**
349f0 20 45 61 63 68 20 6e 65 77 20 56 46 53 20 62 65   Each new VFS be
34a00 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c  comes the defaul
34a10 74 20 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b  t VFS if the mak
34a20 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65  eDflt flag is se
34a30 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65 20 56  t..** The same V
34a40 46 53 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  FS can be regist
34a50 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
34a60 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75  mes without inju
34a70 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20 61  ry..** To make a
34a80 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20 69  n existing VFS i
34a90 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20  nto the default 
34aa0 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69 74  VFS, register it
34ab0 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74   again.** with t
34ac0 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67  he makeDflt flag
34ad0 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64 69   set.  If two di
34ae0 66 66 65 72 65 6e 74 20 56 46 53 65 73 20 77 69  fferent VFSes wi
34af0 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e  th the.** same n
34b00 61 6d 65 20 61 72 65 20 72 65 67 69 73 74 65 72  ame are register
34b10 65 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ed, the behavior
34b20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
34b30 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72  If a.** VFS is r
34b40 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 61  egistered with a
34b50 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e 55   name that is NU
34b60 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73  LL or an empty s
34b70 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74  tring,.** then t
34b80 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
34b90 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
34ba0 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 46 53  Unregister a VFS
34bb0 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74 65   with the sqlite
34bc0 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
34bd0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  () interface..**
34be0 20 49 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   If the default 
34bf0 56 46 53 20 69 73 20 75 6e 72 65 67 69 73 74 65  VFS is unregiste
34c00 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53  red, another VFS
34c10 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a   is chosen as.**
34c20 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54   the default.  T
34c30 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68  he choice for th
34c40 65 20 6e 65 77 20 56 46 53 20 69 73 20 61 72 62  e new VFS is arb
34c50 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 52 65  itrary..**.** Re
34c60 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
34c70 48 31 31 32 30 33 5d 20 5b 48 31 31 32 30 36 5d  H11203] [H11206]
34c80 20 5b 48 31 31 32 30 39 5d 20 5b 48 31 31 32 31   [H11209] [H1121
34c90 32 5d 20 5b 48 31 31 32 31 35 5d 20 5b 48 31 31  2] [H11215] [H11
34ca0 32 31 38 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  218].*/.sqlite3_
34cb0 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66 73  vfs *sqlite3_vfs
34cc0 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61 72  _find(const char
34cd0 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74   *zVfsName);.int
34ce0 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67   sqlite3_vfs_reg
34cf0 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66  ister(sqlite3_vf
34d00 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74  s*, int makeDflt
34d10 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
34d20 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73 71  fs_unregister(sq
34d30 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a  lite3_vfs*);../*
34d40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
34d50 74 65 78 65 73 20 7b 48 31 37 30 30 30 7d 20 3c  texes {H17000} <
34d60 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20000>.**.** Th
34d70 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
34d80 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  es these routine
34d90 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20  s for thread.** 
34da0 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e  synchronization.
34db0 20 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65   Though they are
34dc0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e   intended for in
34dd0 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79  ternal.** use by
34de0 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68   SQLite, code th
34df0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
34e00 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65   SQLite is.** pe
34e10 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61  rmitted to use a
34e20 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
34e30 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
34e40 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f  SQLite source co
34e50 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74  de contains mult
34e60 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
34e70 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65  ions.** of these
34e80 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
34e90 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65    An appropriate
34ea0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
34eb0 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61  ** is selected a
34ec0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20  utomatically at 
34ed0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 54  compile-time.  T
34ee0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  he following.** 
34ef0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
34f00 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  are available in
34f10 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
34f20 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
34f30 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
34f40 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20  TEX_OS2.** <li> 
34f50 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50    SQLITE_MUTEX_P
34f60 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20  THREAD.** <li>  
34f70 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33   SQLITE_MUTEX_W3
34f80 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49  2.** <li>   SQLI
34f90 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a  TE_MUTEX_NOOP.**
34fa0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
34fb0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f   SQLITE_MUTEX_NO
34fc0 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  OP implementatio
34fd0 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f  n is a set of ro
34fe0 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20 64  utines.** that d
34ff0 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b  oes no real lock
35000 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f  ing and is appro
35010 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 69  priate for use i
35020 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68  n.** a single-th
35030 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
35040 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  on.  The SQLITE_
35050 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51  MUTEX_OS2,.** SQ
35060 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45  LITE_MUTEX_PTHRE
35070 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  AD, and SQLITE_M
35080 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65  UTEX_W32 impleme
35090 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20  ntations.** are 
350a0 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
350b0 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69  use on OS/2, Uni
350c0 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73 2e 0a  x, and Windows..
350d0 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20  **.** If SQLite 
350e0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
350f0 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45   the SQLITE_MUTE
35100 58 5f 41 50 50 44 45 46 20 70 72 65 70 72 6f 63  X_APPDEF preproc
35110 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64  essor.** macro d
35120 65 66 69 6e 65 64 20 28 77 69 74 68 20 22 2d 44  efined (with "-D
35130 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50  SQLITE_MUTEX_APP
35140 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f  DEF=1"), then no
35150 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d   mutex.** implem
35160 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c  entation is incl
35170 75 64 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  uded with the li
35180 62 72 61 72 79 2e 20 49 6e 20 74 68 69 73 20 63  brary. In this c
35190 61 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69  ase the.** appli
351a0 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70  cation must supp
351b0 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d 75 74 65  ly a custom mute
351c0 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  x implementation
351d0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53   using the.** [S
351e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
351f0 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20 74 68  EX] option of th
35200 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
35210 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 62  () function.** b
35220 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 73 71  efore calling sq
35230 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
35240 28 29 20 6f 72 20 61 6e 79 20 6f 74 68 65 72 20  () or any other 
35250 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 0a  public sqlite3_.
35260 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ** function that
35270 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
35280 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a  nitialize()..**.
35290 2a 2a 20 7b 48 31 37 30 31 31 7d 20 54 68 65 20  ** {H17011} The 
352a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
352b0 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c  loc() routine al
352c0 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a  locates a new.**
352d0 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75 72   mutex and retur
352e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
352f0 69 74 2e 20 7b 48 31 37 30 31 32 7d 20 49 66 20  it. {H17012} If 
35300 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a  it returns NULL.
35310 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ** that means th
35320 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64  at a mutex could
35330 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 65   not be allocate
35340 64 2e 20 7b 48 31 37 30 31 33 7d 20 53 51 4c 69  d. {H17013} SQLi
35350 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e  te.** will unwin
35360 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20  d its stack and 
35370 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
35380 20 7b 48 31 37 30 31 34 7d 20 54 68 65 20 61 72   {H17014} The ar
35390 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
353a0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
353b0 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  () is one of the
353c0 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
353d0 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ants:.**.** <ul>
353e0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
353f0 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c  _MUTEX_FAST.** <
35400 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
35410 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c  X_RECURSIVE.** <
35420 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
35430 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 0a  X_STATIC_MASTER.
35440 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
35450 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
35460 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
35470 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
35480 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  M2.** <li>  SQLI
35490 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
354a0 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  PRNG.** <li>  SQ
354b0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
354c0 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53  C_LRU.** <li>  S
354d0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
354e0 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e  IC_LRU2.** </ul>
354f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 35 7d 20  .**.** {H17015} 
35500 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63 6f  The first two co
35510 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20 73 71  nstants cause sq
35520 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
35530 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a  c() to create.**
35540 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 54   a new mutex.  T
35550 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20  he new mutex is 
35560 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20 53  recursive when S
35570 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
35580 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64  RSIVE.** is used
35590 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61   but not necessa
355a0 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c  rily so when SQL
355b0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69  ITE_MUTEX_FAST i
355c0 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  s used. {END}.**
355d0 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c 65   The mutex imple
355e0 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e  mentation does n
355f0 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20  ot need to make 
35600 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  a distinction.**
35610 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
35620 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20  MUTEX_RECURSIVE 
35630 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  and SQLITE_MUTEX
35640 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f 65 73  _FAST if it does
35650 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e  .** not want to.
35660 20 20 7b 48 31 37 30 31 36 7d 20 42 75 74 20 53    {H17016} But S
35670 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
35680 72 65 71 75 65 73 74 20 61 20 72 65 63 75 72 73  request a recurs
35690 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20  ive mutex in.** 
356a0 63 61 73 65 73 20 77 68 65 72 65 20 69 74 20 72  cases where it r
356b0 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e  eally needs one.
356c0 20 20 7b 45 4e 44 7d 20 49 66 20 61 20 66 61 73    {END} If a fas
356d0 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76  ter non-recursiv
356e0 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65  e mutex.** imple
356f0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 76 61  mentation is ava
35700 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f  ilable on the ho
35710 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65  st platform, the
35720 20 6d 75 74 65 78 20 73 75 62 73 79 73 74 65 6d   mutex subsystem
35730 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 72 6e  .** might return
35740 20 73 75 63 68 20 61 20 6d 75 74 65 78 20 69 6e   such a mutex in
35750 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c   response to SQL
35760 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a  ITE_MUTEX_FAST..
35770 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 37 7d 20 54  **.** {H17017} T
35780 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64  he other allowed
35790 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 73   parameters to s
357a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
357b0 6f 63 28 29 20 65 61 63 68 20 72 65 74 75 72 6e  oc() each return
357c0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
357d0 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78 69   a static preexi
357e0 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 7b 45 4e  sting mutex. {EN
357f0 44 7d 20 20 53 69 78 20 73 74 61 74 69 63 20 6d  D}  Six static m
35800 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73  utexes are.** us
35810 65 64 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  ed by the curren
35820 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  t version of SQL
35830 69 74 65 2e 20 20 46 75 74 75 72 65 20 76 65 72  ite.  Future ver
35840 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
35850 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69 74  ** may add addit
35860 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74  ional static mut
35870 65 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75  exes.  Static mu
35880 74 65 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e  texes are for in
35890 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79  ternal.** use by
358a0 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41   SQLite only.  A
358b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
358c0 20 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65   use SQLite mute
358d0 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73  xes should.** us
358e0 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d  e only the dynam
358f0 69 63 20 6d 75 74 65 78 65 73 20 72 65 74 75 72  ic mutexes retur
35900 6e 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55  ned by SQLITE_MU
35910 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53  TEX_FAST or.** S
35920 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
35930 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  RSIVE..**.** {H1
35940 37 30 31 38 7d 20 4e 6f 74 65 20 74 68 61 74 20  7018} Note that 
35950 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79  if one of the dy
35960 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61  namic mutex para
35970 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d  meters (SQLITE_M
35980 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20  UTEX_FAST.** or 
35990 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
359a0 55 52 53 49 56 45 29 20 69 73 20 75 73 65 64 20  URSIVE) is used 
359b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74  then sqlite3_mut
359c0 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65  ex_alloc().** re
359d0 74 75 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e  turns a differen
359e0 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79  t mutex on every
359f0 20 63 61 6c 6c 2e 20 20 7b 48 31 37 30 33 34 7d   call.  {H17034}
35a00 20 42 75 74 20 66 6f 72 20 74 68 65 20 73 74 61   But for the sta
35a10 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70  tic.** mutex typ
35a20 65 73 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 74  es, the same mut
35a30 65 78 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f  ex is returned o
35a40 6e 20 65 76 65 72 79 20 63 61 6c 6c 20 74 68 61  n every call tha
35a50 74 20 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d  t has.** the sam
35a60 65 20 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a  e type number..*
35a70 2a 0a 2a 2a 20 7b 48 31 37 30 31 39 7d 20 54 68  *.** {H17019} Th
35a80 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
35a90 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64  free() routine d
35aa0 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65  eallocates a pre
35ab0 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63  viously.** alloc
35ac0 61 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74  ated dynamic mut
35ad0 65 78 2e 20 7b 48 31 37 30 32 30 7d 20 53 51 4c  ex. {H17020} SQL
35ae0 69 74 65 20 69 73 20 63 61 72 65 66 75 6c 20 74  ite is careful t
35af0 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65  o deallocate eve
35b00 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75  ry.** dynamic mu
35b10 74 65 78 20 74 68 61 74 20 69 74 20 61 6c 6c 6f  tex that it allo
35b20 63 61 74 65 73 2e 20 7b 41 31 37 30 32 31 7d 20  cates. {A17021} 
35b30 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  The dynamic mute
35b40 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  xes must not be 
35b50 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74  in.** use when t
35b60 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  hey are dealloca
35b70 74 65 64 2e 20 7b 41 31 37 30 32 32 7d 20 41 74  ted. {A17022} At
35b80 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c  tempting to deal
35b90 6c 6f 63 61 74 65 20 61 20 73 74 61 74 69 63 0a  locate a static.
35ba0 2a 2a 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73  ** mutex results
35bb0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
35bc0 68 61 76 69 6f 72 2e 20 7b 48 31 37 30 32 33 7d  havior. {H17023}
35bd0 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65   SQLite never de
35be0 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73  allocates.** a s
35bf0 74 61 74 69 63 20 6d 75 74 65 78 2e 20 7b 45 4e  tatic mutex. {EN
35c00 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  D}.**.** The sql
35c10 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
35c20 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  () and sqlite3_m
35c30 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69  utex_try() routi
35c40 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74  nes attempt.** t
35c50 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e  o enter a mutex.
35c60 20 7b 48 31 37 30 32 34 7d 20 49 66 20 61 6e 6f   {H17024} If ano
35c70 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20 61  ther thread is a
35c80 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20 74 68  lready within th
35c90 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69  e mutex,.** sqli
35ca0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
35cb0 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64  ) will block and
35cc0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
35cd0 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e  ry() will return
35ce0 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  .** SQLITE_BUSY.
35cf0 20 7b 48 31 37 30 32 35 7d 20 20 54 68 65 20 73   {H17025}  The s
35d00 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
35d10 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
35d20 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
35d30 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73 73  .** upon success
35d40 66 75 6c 20 65 6e 74 72 79 2e 20 20 7b 48 31 37  ful entry.  {H17
35d50 30 32 36 7d 20 4d 75 74 65 78 65 73 20 63 72 65  026} Mutexes cre
35d60 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51  ated using.** SQ
35d70 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
35d80 53 49 56 45 20 63 61 6e 20 62 65 20 65 6e 74 65  SIVE can be ente
35d90 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
35da0 65 73 20 62 79 20 74 68 65 20 73 61 6d 65 20 74  es by the same t
35db0 68 72 65 61 64 2e 0a 2a 2a 20 7b 48 31 37 30 32  hread..** {H1702
35dc0 37 7d 20 49 6e 20 73 75 63 68 20 63 61 73 65 73  7} In such cases
35dd0 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d   the,.** mutex m
35de0 75 73 74 20 62 65 20 65 78 69 74 65 64 20 61 6e  ust be exited an
35df0 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66   equal number of
35e00 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61 6e   times before an
35e10 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
35e20 63 61 6e 20 65 6e 74 65 72 2e 20 20 7b 41 31 37  can enter.  {A17
35e30 30 32 38 7d 20 49 66 20 74 68 65 20 73 61 6d 65  028} If the same
35e40 20 74 68 72 65 61 64 20 74 72 69 65 73 20 74 6f   thread tries to
35e50 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72   enter any other
35e60 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65  .** kind of mute
35e70 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  x more than once
35e80 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
35e90 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
35ea0 7b 48 31 37 30 32 39 7d 20 53 51 4c 69 74 65 20  {H17029} SQLite 
35eb0 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62  will never exhib
35ec0 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76  it.** such behav
35ed0 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75  ior in its own u
35ee0 73 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 0a 2a  se of mutexes..*
35ef0 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79 73 74 65 6d  *.** Some system
35f00 73 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  s (for example, 
35f10 57 69 6e 64 6f 77 73 20 39 35 29 20 64 6f 20 6e  Windows 95) do n
35f20 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65 20 6f  ot support the o
35f30 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  peration.** impl
35f40 65 6d 65 6e 74 65 64 20 62 79 20 73 71 6c 69 74  emented by sqlit
35f50 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2e 20  e3_mutex_try(). 
35f60 20 4f 6e 20 74 68 6f 73 65 20 73 79 73 74 65 6d   On those system
35f70 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s, sqlite3_mutex
35f80 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c 6c 20 61  _try().** will a
35f90 6c 77 61 79 73 20 72 65 74 75 72 6e 20 53 51 4c  lways return SQL
35fa0 49 54 45 5f 42 55 53 59 2e 20 20 7b 48 31 37 30  ITE_BUSY.  {H170
35fb0 33 30 7d 20 54 68 65 20 53 51 4c 69 74 65 20 63  30} The SQLite c
35fc0 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73  ore only ever us
35fd0 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  es.** sqlite3_mu
35fe0 74 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20  tex_try() as an 
35ff0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20  optimization so 
36000 74 68 69 73 20 69 73 20 61 63 63 65 70 74 61 62  this is acceptab
36010 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  le behavior..**.
36020 2a 2a 20 7b 48 31 37 30 33 31 7d 20 54 68 65 20  ** {H17031} The 
36030 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
36040 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78  ave() routine ex
36050 69 74 73 20 61 20 6d 75 74 65 78 20 74 68 61 74  its a mutex that
36060 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
36070 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68  ly entered by th
36080 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20  e same thread.  
36090 7b 41 31 37 30 33 32 7d 20 54 68 65 20 62 65 68  {A17032} The beh
360a0 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65  avior.** is unde
360b0 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74  fined if the mut
360c0 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  ex is not curren
360d0 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74  tly entered by t
360e0 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68  he.** calling th
360f0 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63  read or is not c
36100 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74  urrently allocat
36110 65 64 2e 20 20 7b 48 31 37 30 33 33 7d 20 53 51  ed.  {H17033} SQ
36120 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76  Lite will.** nev
36130 65 72 20 64 6f 20 65 69 74 68 65 72 2e 20 7b 45  er do either. {E
36140 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ND}.**.** If the
36150 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
36160 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
36170 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  (), sqlite3_mute
36180 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a 2a 20 73  x_try(), or.** s
36190 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
361a0 76 65 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ve() is a NULL p
361b0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 61 6c 6c  ointer, then all
361c0 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 0a   three routines.
361d0 2a 2a 20 62 65 68 61 76 65 20 61 73 20 6e 6f 2d  ** behave as no-
361e0 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ops..**.** See a
361f0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  lso: [sqlite3_mu
36200 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20  tex_held()] and 
36210 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e  [sqlite3_mutex_n
36220 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71  otheld()]..*/.sq
36230 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c  lite3_mutex *sql
36240 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
36250 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69  (int);.void sqli
36260 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 73  te3_mutex_free(s
36270 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
36280 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74  void sqlite3_mut
36290 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 65 33  ex_enter(sqlite3
362a0 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71  _mutex*);.int sq
362b0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
362c0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
362d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75  .void sqlite3_mu
362e0 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 65  tex_leave(sqlite
362f0 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a  3_mutex*);../*.*
36300 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
36310 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  x Methods Object
36320 20 7b 48 31 37 31 32 30 7d 20 3c 53 32 30 31 33   {H17120} <S2013
36330 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
36340 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  AL.**.** An inst
36350 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
36360 75 63 74 75 72 65 20 64 65 66 69 6e 65 73 20 74  ucture defines t
36370 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f 75  he low-level rou
36380 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f  tines.** used to
36390 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20 75 73   allocate and us
363a0 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a  e mutexes..**.**
363b0 20 55 73 75 61 6c 6c 79 2c 20 74 68 65 20 64 65   Usually, the de
363c0 66 61 75 6c 74 20 6d 75 74 65 78 20 69 6d 70 6c  fault mutex impl
363d0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72 6f 76  ementations prov
363e0 69 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  ided by SQLite a
363f0 72 65 0a 2a 2a 20 73 75 66 66 69 63 69 65 6e 74  re.** sufficient
36400 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 75 73  , however the us
36410 65 72 20 68 61 73 20 74 68 65 20 6f 70 74 69 6f  er has the optio
36420 6e 20 6f 66 20 73 75 62 73 74 69 74 75 74 69 6e  n of substitutin
36430 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d  g a custom.** im
36440 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  plementation for
36450 20 73 70 65 63 69 61 6c 69 7a 65 64 20 64 65 70   specialized dep
36460 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79 73 74  loyments or syst
36470 65 6d 73 20 66 6f 72 20 77 68 69 63 68 20 53 51  ems for which SQ
36480 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  Lite.** does not
36490 20 70 72 6f 76 69 64 65 20 61 20 73 75 69 74 61   provide a suita
364a0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
364b0 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65  on. In this case
364c0 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 63 72  , the user.** cr
364d0 65 61 74 65 73 20 61 6e 64 20 70 6f 70 75 6c 61  eates and popula
364e0 74 65 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  tes an instance 
364f0 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
36500 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74 6f 20  e to pass.** to 
36510 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
36520 20 61 6c 6f 6e 67 20 77 69 74 68 20 74 68 65 20   along with the 
36530 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
36540 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  UTEX] option..**
36550 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 61   Additionally, a
36560 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
36570 69 73 20 73 74 72 75 63 74 75 72 65 20 63 61 6e  is structure can
36580 20 62 65 20 75 73 65 64 20 61 73 20 61 6e 0a 2a   be used as an.*
36590 2a 20 6f 75 74 70 75 74 20 76 61 72 69 61 62 6c  * output variabl
365a0 65 20 77 68 65 6e 20 71 75 65 72 79 69 6e 67 20  e when querying 
365b0 74 68 65 20 73 79 73 74 65 6d 20 66 6f 72 20 74  the system for t
365c0 68 65 20 63 75 72 72 65 6e 74 20 6d 75 74 65 78  he current mutex
365d0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
365e0 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65 20 5b 53  on, using the [S
365f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
36600 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a  MUTEX] option..*
36610 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 49  *.** The xMutexI
36620 6e 69 74 20 6d 65 74 68 6f 64 20 64 65 66 69 6e  nit method defin
36630 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63  ed by this struc
36640 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  ture is invoked 
36650 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79  as.** part of sy
36660 73 74 65 6d 20 69 6e 69 74 69 61 6c 69 7a 61 74  stem initializat
36670 69 6f 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74  ion by the sqlit
36680 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
36690 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 7b 48 31  function..** {H1
366a0 37 30 30 31 7d 20 54 68 65 20 78 4d 75 74 65 78  7001} The xMutex
366b0 49 6e 69 74 20 72 6f 75 74 69 6e 65 20 73 68 61  Init routine sha
366c0 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 79 20  ll be called by 
366d0 53 51 4c 69 74 65 20 6f 6e 63 65 20 66 6f 72 20  SQLite once for 
366e0 65 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76  each.** effectiv
366f0 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  e call to [sqlit
36700 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
36710 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74  ..**.** The xMut
36720 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66  exEnd method def
36730 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72  ined by this str
36740 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65  ucture is invoke
36750 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
36760 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20  system shutdown 
36770 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
36780 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69  hutdown() functi
36790 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65  on. The.** imple
367a0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69  mentation of thi
367b0 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65  s method is expe
367c0 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20  cted to release 
367d0 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a  all outstanding.
367e0 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74  ** resources obt
367f0 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74  ained by the mut
36800 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65  ex methods imple
36810 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63  mentation, espec
36820 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f  ially.** those o
36830 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 78  btained by the x
36840 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64  MutexInit method
36850 2e 20 7b 48 31 37 30 30 33 7d 20 54 68 65 20 78  . {H17003} The x
36860 4d 75 74 65 78 45 6e 64 28 29 0a 2a 2a 20 69 6e  MutexEnd().** in
36870 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62 65  terface shall be
36880 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f   invoked once fo
36890 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  r each call to [
368a0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
368b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72  ()]..**.** The r
368c0 65 6d 61 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d  emaining seven m
368d0 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 20 62  ethods defined b
368e0 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  y this structure
368f0 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a   (xMutexAlloc,.*
36900 2a 20 78 4d 75 74 65 78 46 72 65 65 2c 20 78 4d  * xMutexFree, xM
36910 75 74 65 78 45 6e 74 65 72 2c 20 78 4d 75 74 65  utexEnter, xMute
36920 78 54 72 79 2c 20 78 4d 75 74 65 78 4c 65 61 76  xTry, xMutexLeav
36930 65 2c 20 78 4d 75 74 65 78 48 65 6c 64 20 61 6e  e, xMutexHeld an
36940 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65  d.** xMutexNothe
36950 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  ld) implement th
36960 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  e following inte
36970 72 66 61 63 65 73 20 28 72 65 73 70 65 63 74 69  rfaces (respecti
36980 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  vely):.**.** <ul
36990 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71  >.**   <li>  [sq
369a0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
369b0 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  c()] </li>.**   
369c0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
369d0 75 74 65 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c  utex_free()] </l
369e0 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
369f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
36a00 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  er()] </li>.**  
36a10 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
36a20 6d 75 74 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c  mutex_try()] </l
36a30 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
36a40 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
36a50 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  ve()] </li>.**  
36a60 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
36a70 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f  mutex_held()] </
36a80 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
36a90 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
36aa0 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  theld()] </li>.*
36ab0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
36ac0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
36ad0 65 20 69 73 20 74 68 61 74 20 74 68 65 20 70 75  e is that the pu
36ae0 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58  blic sqlite3_XXX
36af0 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65   functions enume
36b00 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73  rated.** above s
36b10 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61  ilently ignore a
36b20 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74  ny invocations t
36b30 68 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20  hat pass a NULL 
36b40 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a  pointer instead.
36b50 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75  ** of a valid mu
36b60 74 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20  tex handle. The 
36b70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
36b80 6f 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64  of the methods d
36b90 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69  efined.** by thi
36ba0 73 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20  s structure are 
36bb0 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20  not required to 
36bc0 68 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65  handle this case
36bd0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a  , the results.**
36be0 20 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55   of passing a NU
36bf0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  LL pointer inste
36c00 61 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75  ad of a valid mu
36c10 74 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75  tex handle are u
36c20 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65  ndefined.** (i.e
36c30 2e 20 69 74 20 69 73 20 61 63 63 65 70 74 61 62  . it is acceptab
36c40 6c 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e  le to provide an
36c50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36c60 74 68 61 74 20 73 65 67 66 61 75 6c 74 73 20 69  that segfaults i
36c70 66 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65  f.** it is passe
36c80 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
36c90 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75  )..**.** The xMu
36ca0 74 65 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64  texInit() method
36cb0 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
36cc0 61 66 65 2e 20 20 49 74 20 6d 75 73 74 20 62 65  afe.  It must be
36cd0 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20   harmless to.** 
36ce0 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69  invoke xMutexIni
36cf0 74 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d 65  t() mutiple time
36d00 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
36d10 65 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77 69  e process and wi
36d20 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65  thout.** interve
36d30 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d  ning calls to xM
36d40 75 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63 6f  utexEnd().  Seco
36d50 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
36d60 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d  t calls to.** xM
36d70 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20  utexInit() must 
36d80 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  be no-ops..**.**
36d90 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75   xMutexInit() mu
36da0 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74  st not use SQLit
36db0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
36dc0 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d 61  ion ([sqlite3_ma
36dd0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20 69  lloc()].** and i
36de0 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e 20  ts associates). 
36df0 20 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75 74   Similarly, xMut
36e00 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20 6e  exAlloc() must n
36e10 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 65  ot use SQLite me
36e20 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
36e30 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69 63 20  on for a static 
36e40 6d 75 74 65 78 2e 20 20 48 6f 77 65 76 65 72 20  mutex.  However 
36e50 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 61  xMutexAlloc() ma
36e60 79 20 75 73 65 20 53 51 4c 69 74 65 0a 2a 2a 20  y use SQLite.** 
36e70 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
36e80 6e 20 66 6f 72 20 61 20 66 61 73 74 20 6f 72 20  n for a fast or 
36e90 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 2e  recursive mutex.
36ea0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
36eb0 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 78 4d  ll invoke the xM
36ec0 75 74 65 78 45 6e 64 28 29 20 6d 65 74 68 6f 64  utexEnd() method
36ed0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   when [sqlite3_s
36ee0 68 75 74 64 6f 77 6e 28 29 5d 20 69 73 0a 2a 2a  hutdown()] is.**
36ef0 20 63 61 6c 6c 65 64 2c 20 62 75 74 20 6f 6e 6c   called, but onl
36f00 79 20 69 66 20 74 68 65 20 70 72 69 6f 72 20 63  y if the prior c
36f10 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78 49 6e 69  all to xMutexIni
36f20 74 20 72 65 74 75 72 6e 65 64 20 53 51 4c 49 54  t returned SQLIT
36f30 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d 75 74  E_OK..** If xMut
36f40 65 78 49 6e 69 74 20 66 61 69 6c 73 20 69 6e 20  exInit fails in 
36f50 61 6e 79 20 77 61 79 2c 20 69 74 20 69 73 20 65  any way, it is e
36f60 78 70 65 63 74 65 64 20 74 6f 20 63 6c 65 61 6e  xpected to clean
36f70 20 75 70 20 61 66 74 65 72 20 69 74 73 65 6c 66   up after itself
36f80 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 72 65 74  .** prior to ret
36f90 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70 65 64  urning..*/.typed
36fa0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
36fb0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20  3_mutex_methods 
36fc0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
36fd0 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
36fe0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
36ff0 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d  ods {.  int (*xM
37000 75 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b  utexInit)(void);
37010 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45  .  int (*xMutexE
37020 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c  nd)(void);.  sql
37030 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d  ite3_mutex *(*xM
37040 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b  utexAlloc)(int);
37050 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78  .  void (*xMutex
37060 46 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75  Free)(sqlite3_mu
37070 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28  tex *);.  void (
37080 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71  *xMutexEnter)(sq
37090 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
370a0 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72    int (*xMutexTr
370b0 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  y)(sqlite3_mutex
370c0 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d   *);.  void (*xM
370d0 75 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74  utexLeave)(sqlit
370e0 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69  e3_mutex *);.  i
370f0 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29  nt (*xMutexHeld)
37100 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
37110 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
37120 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65  xNotheld)(sqlite
37130 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a  3_mutex *);.};..
37140 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37150 4d 75 74 65 78 20 56 65 72 69 66 69 63 61 74 69  Mutex Verificati
37160 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 37  on Routines {H17
37170 30 38 30 7d 20 3c 53 32 30 31 33 30 3e 20 3c 53  080} <S20130> <S
37180 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30800>.**.** The
37190 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68   sqlite3_mutex_h
371a0 65 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65  eld() and sqlite
371b0 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
371c0 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  ) routines.** ar
371d0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
371e0 73 65 20 69 6e 73 69 64 65 20 61 73 73 65 72 74  se inside assert
371f0 28 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 7b  () statements. {
37200 48 31 37 30 38 31 7d 20 54 68 65 20 53 51 4c 69  H17081} The SQLi
37210 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72  te core.** never
37220 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74   uses these rout
37230 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 69  ines except insi
37240 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 61  de an assert() a
37250 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  nd applications.
37260 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 74  ** are advised t
37270 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61  o follow the lea
37280 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20  d of the core.  
37290 7b 48 31 37 30 38 32 7d 20 54 68 65 20 63 6f 72  {H17082} The cor
372a0 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64  e only.** provid
372b0 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  es implementatio
372c0 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75  ns for these rou
372d0 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73  tines when it is
372e0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
372f0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42  h the SQLITE_DEB
37300 55 47 20 66 6c 61 67 2e 20 20 7b 41 31 37 30 38  UG flag.  {A1708
37310 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65  7} External mute
37320 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  x implementation
37330 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65  s.** are only re
37340 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64  quired to provid
37350 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
37360 20 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47   if SQLITE_DEBUG
37370 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61   is.** defined a
37380 6e 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 20  nd if NDEBUG is 
37390 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  not defined..**.
373a0 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54 68 65 73  ** {H17083} Thes
373b0 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  e routines shoul
373c0 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66  d return true if
373d0 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68   the mutex in th
373e0 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  eir argument.** 
373f0 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68  is held or not h
37400 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c  eld, respectivel
37410 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e  y, by the callin
37420 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  g thread..**.** 
37430 7b 58 31 37 30 38 34 7d 20 54 68 65 20 69 6d 70  {X17084} The imp
37440 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
37450 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 70  ot required to p
37460 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73  rovided versions
37470 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75   of these.** rou
37480 74 69 6e 65 73 20 74 68 61 74 20 61 63 74 75 61  tines that actua
37490 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74 68 65  lly work. If the
374a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
374b0 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65  does not provide
374c0 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73   working.** vers
374d0 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f  ions of these ro
374e0 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c  utines, it shoul
374f0 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69  d at least provi
37500 64 65 20 73 74 75 62 73 20 74 68 61 74 20 61 6c  de stubs that al
37510 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74  ways.** return t
37520 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20  rue so that one 
37530 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75  does not get spu
37540 72 69 6f 75 73 20 61 73 73 65 72 74 69 6f 6e 20  rious assertion 
37550 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20  failures..**.** 
37560 7b 48 31 37 30 38 35 7d 20 49 66 20 74 68 65 20  {H17085} If the 
37570 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
37580 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
37590 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
375a0 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  er then.** the r
375b0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65  outine should re
375c0 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20 54  turn 1.  {END} T
375d0 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65  his seems counte
375e0 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63  r-intuitive sinc
375f0 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65  e.** clearly the
37600 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65   mutex cannot be
37610 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73   held if it does
37620 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74   not exist.  But
37630 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73   the.** the reas
37640 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65  on the mutex doe
37650 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62  s not exist is b
37660 65 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 64  ecause the build
37670 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67   is not.** using
37680 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77   mutexes.  And w
37690 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68  e do not want th
376a0 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61  e assert() conta
376b0 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c  ining the.** cal
376c0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  l to sqlite3_mut
376d0 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69  ex_held() to fai
376e0 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f  l, so a non-zero
376f0 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68   return is.** th
37700 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 68  e appropriate th
37710 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 48 31 37  ing to do.  {H17
37720 30 38 36 7d 20 54 68 65 20 73 71 6c 69 74 65 33  086} The sqlite3
37730 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
37740 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68  .** interface sh
37750 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e  ould also return
37760 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20   1 when given a 
37770 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
37780 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
37790 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 5f  ex_held(sqlite3_
377a0 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c  mutex*);.int sql
377b0 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
377c0 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ld(sqlite3_mutex
377d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
377e0 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70 65 73  REF: Mutex Types
377f0 20 7b 48 31 37 30 30 31 7d 20 3c 48 31 37 30 30   {H17001} <H1700
37800 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0>.**.** The [sq
37810 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
37820 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  c()] interface t
37830 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
37840 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20  gument.** which 
37850 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  is one of these 
37860 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
37870 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 74  s..**.** The set
37880 20 6f 66 20 73 74 61 74 69 63 20 6d 75 74 65 78   of static mutex
37890 65 73 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  es may change fr
378a0 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65 20 72 65  om one SQLite re
378b0 6c 65 61 73 65 20 74 6f 20 74 68 65 0a 2a 2a 20  lease to the.** 
378c0 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
378d0 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 72 69 64  ons that overrid
378e0 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  e the built-in m
378f0 75 74 65 78 20 6c 6f 67 69 63 20 6d 75 73 74 20  utex logic must 
37900 62 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 74  be.** prepared t
37910 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20 61 64  o accommodate ad
37920 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20  ditional static 
37930 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 65 66  mutexes..*/.#def
37940 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
37950 5f 46 41 53 54 20 20 20 20 20 20 20 20 20 20 20  _FAST           
37960 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
37970 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
37980 56 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  VE        1.#def
37990 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
379a0 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 20 20  _STATIC_MASTER  
379b0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
379c0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
379d0 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f 2a 20  MEM       3  /* 
379e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
379f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
37a00 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
37a10 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f 2a 20  MEM2      4  /* 
37a20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23 64 65 66  NOT USED */.#def
37a30 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
37a40 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20 20 20 20  _STATIC_OPEN    
37a50 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 42    4  /* sqlite3B
37a60 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f 0a 23 64  treeOpen() */.#d
37a70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
37a80 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 20  EX_STATIC_PRNG  
37a90 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
37aa0 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64  3_random() */.#d
37ab0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
37ac0 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 20  EX_STATIC_LRU   
37ad0 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 61      6  /* lru pa
37ae0 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66 69  ge list */.#defi
37af0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
37b00 53 54 41 54 49 43 5f 4c 52 55 32 20 20 20 20 20  STATIC_LRU2     
37b10 20 37 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20   7  /* lru page 
37b20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  list */../*.** C
37b30 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
37b40 65 20 74 68 65 20 6d 75 74 65 78 20 66 6f 72 20  e the mutex for 
37b50 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
37b60 63 74 69 6f 6e 20 7b 48 31 37 30 30 32 7d 20 3c  ction {H17002} <
37b70 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H17000>.**.** Th
37b80 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
37b90 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
37ba0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
37bb0 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 0a  x] object that .
37bc0 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 20 61 63  ** serializes ac
37bd0 63 65 73 73 20 74 6f 20 74 68 65 20 5b 64 61 74  cess to the [dat
37be0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37bf0 5d 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 61  ] given in the a
37c00 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e 20  rgument.** when 
37c10 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
37c20 6f 64 65 5d 20 69 73 20 53 65 72 69 61 6c 69 7a  ode] is Serializ
37c30 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 74  ed..** If the [t
37c40 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
37c50 73 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s Single-thread 
37c60 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  or Multi-thread 
37c70 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f 75  then this.** rou
37c80 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
37c90 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
37ca0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73  sqlite3_mutex *s
37cb0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 28  qlite3_db_mutex(
37cc0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
37cd0 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d  * CAPI3REF: Low-
37ce0 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66  Level Control Of
37cf0 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 20   Database Files 
37d00 7b 48 31 31 33 30 30 7d 20 3c 53 33 30 38 30 30  {H11300} <S30800
37d10 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31 7d  >.**.** {H11301}
37d20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   The [sqlite3_fi
37d30 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
37d40 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
37d50 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74  direct call to t
37d60 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72  he.** xFileContr
37d70 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68  ol method for th
37d80 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
37d90 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73  thods] object as
37da0 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
37db0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
37dc0 74 61 62 61 73 65 20 69 64 65 6e 74 69 66 69 65  tabase identifie
37dd0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
37de0 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33 30  argument. {H1130
37df0 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f  2} The.** name o
37e00 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
37e10 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  s the name assig
37e20 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74 61 62  ned to the datab
37e30 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61  ase by the.** <a
37e40 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61   href="lang_atta
37e50 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c  ch.html">ATTACH<
37e60 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20  /a> SQL command 
37e70 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65 0a  that opened the.
37e80 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b 48 31  ** database. {H1
37e90 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 6c  1303} To control
37ea0 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
37eb0 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74 68 65  se file, use the
37ec0 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a 20   name "main".** 
37ed0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
37ee0 72 2e 20 7b 48 31 31 33 30 34 7d 20 54 68 65 20  r. {H11304} The 
37ef0 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
37f00 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
37f10 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61  his routine.** a
37f20 72 65 20 70 61 73 73 65 64 20 64 69 72 65 63 74  re passed direct
37f30 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ly through to th
37f40 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69  e second and thi
37f50 72 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  rd parameters of
37f60 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  .** the xFileCon
37f70 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b 48  trol method.  {H
37f80 31 31 33 30 35 7d 20 54 68 65 20 72 65 74 75 72  11305} The retur
37f90 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 78  n value of the x
37fa0 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d  FileControl.** m
37fb0 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 68  ethod becomes th
37fc0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
37fd0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a  f this routine..
37fe0 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20 49  **.** {H11306} I
37ff0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
38000 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d 65 29  ameter (zDbName)
38010 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20   does not match 
38020 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a  the name of any.
38030 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  ** open database
38040 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49   file, then SQLI
38050 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65 74 75  TE_ERROR is retu
38060 72 6e 65 64 2e 20 7b 48 31 31 33 30 37 7d 20 54  rned. {H11307} T
38070 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  his error.** cod
38080 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65  e is not remembe
38090 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74  red and will not
380a0 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20   be recalled by 
380b0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
380c0 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
380d0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b 41  e3_errmsg()]. {A
380e0 31 31 33 30 38 7d 20 54 68 65 20 75 6e 64 65 72  11308} The under
380f0 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72  lying xFileContr
38100 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a  ol method might.
38110 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 53  ** also return S
38120 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b 41  QLITE_ERROR.  {A
38130 31 31 33 30 39 7d 20 54 68 65 72 65 20 69 73 20  11309} There is 
38140 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74 69 6e  no way to distin
38150 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a  guish between.**
38160 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a 44   an incorrect zD
38170 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c  bName and an SQL
38180 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75 72 6e  ITE_ERROR return
38190 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c   from the underl
381a0 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e  ying.** xFileCon
381b0 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 4e  trol method. {EN
381c0 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  D}.**.** See als
381d0 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  o: [SQLITE_FCNTL
381e0 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69  _LOCKSTATE].*/.i
381f0 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  nt sqlite3_file_
38200 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a  control(sqlite3*
38210 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44  , const char *zD
38220 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76  bName, int op, v
38230 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
38240 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20  PI3REF: Testing 
38250 49 6e 74 65 72 66 61 63 65 20 7b 48 31 31 34 30  Interface {H1140
38260 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a  0} <S30800>.**.*
38270 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 65  * The sqlite3_te
38280 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e 74  st_control() int
38290 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
382a0 6f 20 72 65 61 64 20 6f 75 74 20 69 6e 74 65 72  o read out inter
382b0 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66 20  nal.** state of 
382c0 53 51 4c 69 74 65 20 61 6e 64 20 74 6f 20 69 6e  SQLite and to in
382d0 6a 65 63 74 20 66 61 75 6c 74 73 20 69 6e 74 6f  ject faults into
382e0 20 53 51 4c 69 74 65 20 66 6f 72 20 74 65 73 74   SQLite for test
382f0 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73 2e  ing.** purposes.
38300 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
38310 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 65 72  meter is an oper
38320 61 74 69 6f 6e 20 63 6f 64 65 20 74 68 61 74 20  ation code that 
38330 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74 68  determines.** th
38340 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69 6e  e number, meanin
38350 67 2c 20 61 6e 64 20 6f 70 65 72 61 74 69 6f 6e  g, and operation
38360 20 6f 66 20 61 6c 6c 20 73 75 62 73 65 71 75 65   of all subseque
38370 6e 74 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  nt parameters..*
38380 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
38390 61 63 65 20 69 73 20 6e 6f 74 20 66 6f 72 20 75  ace is not for u
383a0 73 65 20 62 79 20 61 70 70 6c 69 63 61 74 69 6f  se by applicatio
383b0 6e 73 2e 20 20 49 74 20 65 78 69 73 74 73 20 73  ns.  It exists s
383c0 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65 72  olely.** for ver
383d0 69 66 79 69 6e 67 20 74 68 65 20 63 6f 72 72 65  ifying the corre
383e0 63 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ct operation of 
383f0 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
38400 72 79 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a 2a  ry.  Depending.*
38410 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20 53 51 4c  * on how the SQL
38420 69 74 65 20 6c 69 62 72 61 72 79 20 69 73 20 63  ite library is c
38430 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73 20 69 6e  ompiled, this in
38440 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 6e 6f  terface might no
38450 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54  t exist..**.** T
38460 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
38470 65 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65  e operation code
38480 73 2c 20 74 68 65 69 72 20 6d 65 61 6e 69 6e 67  s, their meaning
38490 73 2c 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  s, the parameter
384a0 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c 20  s.** they take, 
384b0 61 6e 64 20 77 68 61 74 20 74 68 65 79 20 64 6f  and what they do
384c0 20 61 72 65 20 61 6c 6c 20 73 75 62 6a 65 63 74   are all subject
384d0 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f   to change witho
384e0 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55 6e  ut notice..** Un
384f0 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68 65  like most of the
38500 20 53 51 4c 69 74 65 20 41 50 49 2c 20 74 68 69   SQLite API, thi
38510 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f  s function is no
38520 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 0a  t guaranteed to.
38530 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e 73 69  ** operate consi
38540 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e 65  stently from one
38550 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
38560 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  next..*/.int sql
38570 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f  ite3_test_contro
38580 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  l(int op, ...);.
38590 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
385a0 20 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61   Testing Interfa
385b0 63 65 20 4f 70 65 72 61 74 69 6f 6e 20 43 6f 64  ce Operation Cod
385c0 65 73 20 7b 48 31 31 34 31 30 7d 20 3c 48 31 31  es {H11410} <H11
385d0 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  400>.**.** These
385e0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
385f0 68 65 20 76 61 6c 69 64 20 6f 70 65 72 61 74 69  he valid operati
38600 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d 65 74 65  on code paramete
38610 72 73 20 75 73 65 64 0a 2a 2a 20 61 73 20 74 68  rs used.** as th
38620 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
38630 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 65 73   to [sqlite3_tes
38640 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a 2a  t_control()]..**
38650 0a 2a 2a 20 54 68 65 73 65 20 70 61 72 61 6d 65  .** These parame
38660 74 65 72 73 20 61 6e 64 20 74 68 65 69 72 20 6d  ters and their m
38670 65 61 6e 69 6e 67 73 20 61 72 65 20 73 75 62 6a  eanings are subj
38680 65 63 74 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ect to change.**
38690 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e   without notice.
386a0 20 20 54 68 65 73 65 20 76 61 6c 75 65 73 20 61    These values a
386b0 72 65 20 66 6f 72 20 74 65 73 74 69 6e 67 20 70  re for testing p
386c0 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a 2a  urposes only..**
386d0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
386e0 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 61 6e 79  ould not use any
386f0 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
38700 74 65 72 73 20 6f 72 20 74 68 65 0a 2a 2a 20 5b  ters or the.** [
38710 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e  sqlite3_test_con
38720 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
38730 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
38740 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52  LITE_TESTCTRL_PR
38750 4e 47 5f 53 41 56 45 20 20 20 20 20 20 20 20 20  NG_SAVE         
38760 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
38770 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
38780 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45 20 20 20  _PRNG_RESTORE   
38790 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
387a0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
387b0 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45 54 20 20  TRL_PRNG_RESET  
387c0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
387d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
387e0 53 54 43 54