/ Hex Artifact Content
Login

Artifact 5af8181f815831a8672c3834c60e6b4418448bcc:


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 73 68 6f 75 6c 64  lications should
2450: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2460: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61  ze | finalize] a
2470: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
2480: 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20  tements].** and 
2490: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
24a0: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c  ose | close] all
24b0: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20   [BLOB handles] 
24c0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
24d0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ** the [sqlite3]
24e0: 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f   object prior to
24f0: 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63   attempting to c
2500: 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e  lose the object.
2510: 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
2520: 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 20 69 6e  _next_stmt()] in
2530: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
2540: 73 65 64 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  sed to locate al
2550: 6c 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  l.** [prepared s
2560: 74 61 74 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63  tatements] assoc
2570: 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
2580: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2590: 6e 5d 20 69 66 20 64 65 73 69 72 65 64 2e 0a 2a  n] if desired..*
25a0: 2a 20 54 79 70 69 63 61 6c 20 63 6f 64 65 20 6d  * Typical code m
25b0: 69 67 68 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74  ight look like t
25c0: 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
25d0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
25e0: 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
25f0: 74 6d 74 3b 0a 2a 2a 20 77 68 69 6c 65 28 20 28  tmt;.** while( (
2600: 70 53 74 6d 74 20 3d 20 73 71 6c 69 74 65 33 5f  pStmt = sqlite3_
2610: 6e 65 78 74 5f 73 74 6d 74 28 64 62 2c 20 30 29  next_stmt(db, 0)
2620: 29 21 3d 30 20 29 7b 0a 2a 2a 20 26 6e 62 73 70  )!=0 ){.** &nbsp
2630: 3b 20 20 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ;   sqlite3_fina
2640: 6c 69 7a 65 28 70 53 74 6d 74 29 3b 0a 2a 2a 20  lize(pStmt);.** 
2650: 7d 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  }.** </pre></blo
2660: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49  ckquote>.**.** I
2670: 66 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  f [sqlite3_close
2680: 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ()] is invoked w
2690: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
26a0: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
26b0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
26c0: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
26d0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
26e0: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
26f0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
2700: 6c 6f 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65  lose(C)] must be
2710: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a   either a NULL.*
2720: 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20  * pointer or an 
2730: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2740: 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65   pointer obtaine
2750: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
2760: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2770: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
2780: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
2790: 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e  pen_v2()], and n
27a0: 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c  ot previously cl
27b0: 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  osed..**.** Requ
27c0: 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
27d0: 32 30 31 31 5d 20 5b 48 31 32 30 31 32 5d 20 5b  2011] [H12012] [
27e0: 48 31 32 30 31 33 5d 20 5b 48 31 32 30 31 34 5d  H12013] [H12014]
27f0: 20 5b 48 31 32 30 31 35 5d 20 5b 48 31 32 30 31   [H12015] [H1201
2800: 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  9].*/.int sqlite
2810: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20  3_close(sqlite3 
2820: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
2830: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
2840: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
2850: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
2860: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
2870: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
2880: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
2890: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
28a0: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
28b0: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
28c0: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
28d0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
28e0: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
28f0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2900: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
2910: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
2920: 74 65 72 66 61 63 65 20 7b 48 31 32 31 30 30 7d  terface {H12100}
2930: 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10000>.**.** 
2940: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
2950: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2960: 61 20 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79  a convenient way
2970: 20 6f 66 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20   of running one 
2980: 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73  or more.** SQL s
2990: 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75  tatements withou
29a0: 74 20 68 61 76 69 6e 67 20 74 6f 20 77 72 69 74  t having to writ
29b0: 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64  e a lot of C cod
29c0: 65 2e 20 20 54 68 65 20 55 54 46 2d 38 20 65 6e  e.  The UTF-8 en
29d0: 63 6f 64 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  coded.** SQL sta
29e0: 74 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73  tements are pass
29f0: 65 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63  ed in as the sec
2a00: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
2a10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2e   sqlite3_exec().
2a20: 0a 2a 2a 20 54 68 65 20 73 74 61 74 65 6d 65 6e  .** The statemen
2a30: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
2a40: 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75 6e 74 69   one by one unti
2a50: 6c 20 65 69 74 68 65 72 20 61 6e 20 65 72 72 6f  l either an erro
2a60: 72 20 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72  r or.** an inter
2a70: 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65  rupt is encounte
2a80: 72 65 64 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68  red, or until th
2a90: 65 79 20 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e  ey are all done.
2aa0: 20 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65    The 3rd parame
2ab0: 74 65 72 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74  ter.** is an opt
2ac0: 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74  ional callback t
2ad0: 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hat is invoked o
2ae0: 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77  nce for each row
2af0: 20 6f 66 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a   of any query.**
2b00: 20 72 65 73 75 6c 74 73 20 70 72 6f 64 75 63 65   results produce
2b10: 64 20 62 79 20 74 68 65 20 53 51 4c 20 73 74 61  d by the SQL sta
2b20: 74 65 6d 65 6e 74 73 2e 20 20 54 68 65 20 35 74  tements.  The 5t
2b30: 68 20 70 61 72 61 6d 65 74 65 72 20 74 65 6c 6c  h parameter tell
2b40: 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72  s where.** to wr
2b50: 69 74 65 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  ite any error me
2b60: 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ssages..**.** Th
2b70: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
2b80: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
2b90: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
2ba0: 6d 65 74 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a  meter is held.**
2bb0: 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   in memory obtai
2bc0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2bd0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f  3_malloc()].  To
2be0: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
2bf0: 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c  leak,.** the cal
2c00: 6c 69 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e  ling application
2c10: 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71   should call [sq
2c20: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
2c30: 20 61 6e 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   any error.** me
2c40: 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 74  ssage returned t
2c50: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
2c60: 61 72 61 6d 65 74 65 72 20 77 68 65 6e 20 69 74  arameter when it
2c70: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
2c80: 69 6e 67 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  ing.** the error
2c90: 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
2ca0: 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2cb0: 6d 65 6e 74 20 69 6e 20 74 68 65 20 32 6e 64 20  ment in the 2nd 
2cc0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
2cd0: 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74  L or an empty st
2ce0: 72 69 6e 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72  ring.** or a str
2cf0: 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f  ing containing o
2d00: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
2d10: 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  nd comments, the
2d20: 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74  n no SQL.** stat
2d30: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
2d40: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74  ated and the dat
2d50: 61 62 61 73 65 20 69 73 20 6e 6f 74 20 63 68 61  abase is not cha
2d60: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nged..**.** The 
2d70: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
2d80: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
2d90: 65 6d 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73  emented in terms
2da0: 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
2db0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
2dc0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
2dd0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
2de0: 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68  nalize()]..** Th
2df0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2e00: 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
2e10: 74 68 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74  thing to the dat
2e20: 61 62 61 73 65 20 74 68 61 74 20 63 61 6e 6e 6f  abase that canno
2e30: 74 20 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20  t be done.** by 
2e40: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e50: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2e60: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
2e70: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e80: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
2e90: 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
2ea0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2eb0: 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c  ] must be an val
2ec0: 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 5b  id and open.** [
2ed0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2ee0: 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ion]..**.** The 
2ef0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f00: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  ion must not be 
2f10: 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20  closed while.** 
2f20: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2f30: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
2f40: 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66  ** The calling f
2f50: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  unction should u
2f60: 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  se [sqlite3_free
2f70: 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20 74  ()] to free.** t
2f80: 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a  he memory that *
2f90: 65 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70  errmsg is left p
2fa0: 6f 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20  ointing at once 
2fb0: 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
2fc0: 73 61 67 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  sage is no longe
2fd0: 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  r needed..**.** 
2fe0: 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  The SQL statemen
2ff0: 74 20 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e  t text in the 2n
3000: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
3010: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a  sqlite3_exec()].
3020: 2a 2a 20 6d 75 73 74 20 72 65 6d 61 69 6e 20 75  ** must remain u
3030: 6e 63 68 61 6e 67 65 64 20 77 68 69 6c 65 20 5b  nchanged while [
3040: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3050: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
3060: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
3070: 2a 2a 20 5b 48 31 32 31 30 31 5d 20 5b 48 31 32  ** [H12101] [H12
3080: 31 30 32 5d 20 5b 48 31 32 31 30 34 5d 20 5b 48  102] [H12104] [H
3090: 31 32 31 30 35 5d 20 5b 48 31 32 31 30 37 5d 20  12105] [H12107] 
30a0: 5b 48 31 32 31 31 30 5d 20 5b 48 31 32 31 31 33  [H12110] [H12113
30b0: 5d 20 5b 48 31 32 31 31 36 5d 0a 2a 2a 20 5b 48  ] [H12116].** [H
30c0: 31 32 31 31 39 5d 20 5b 48 31 32 31 32 32 5d 20  12119] [H12122] 
30d0: 5b 48 31 32 31 32 35 5d 20 5b 48 31 32 31 33 31  [H12125] [H12131
30e0: 5d 20 5b 48 31 32 31 33 34 5d 20 5b 48 31 32 31  ] [H12134] [H121
30f0: 33 37 5d 20 5b 48 31 32 31 33 38 5d 0a 2a 2f 0a  37] [H12138].*/.
3100: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
3110: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
3120: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3140: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
3150: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
3160: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
3170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3180: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
3190: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
31a0: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
31b0: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
31c0: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
31d0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
31e0: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
31f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3200: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3210: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
3220: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
3230: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
3240: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3250: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
3260: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
3270: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
3280: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
3290: 6c 74 20 43 6f 64 65 73 20 7b 48 31 30 32 31 30  lt Codes {H10210
32a0: 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45  } <S10700>.** KE
32b0: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
32c0: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
32d0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
32e0: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
32f0: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
3300: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
3310: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
3320: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
3330: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
3340: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
3350: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
3360: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
3370: 73 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69  s success or fai
3380: 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  lure..**.** New 
3390: 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20  error codes may 
33a0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
33b0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
33c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  QLite..**.** See
33d0: 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49   also: [SQLITE_I
33e0: 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
33f0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
3400: 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s].*/.#define SQ
3410: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
3420: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
3430: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
3440: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
3450: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
3460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
3470: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
3480: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
3490: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
34a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
34b0: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
34c0: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
34d0: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
34e0: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
34f0: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
3500: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
3510: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
3520: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3530: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
3540: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
3550: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
3560: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
3570: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
3580: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
3590: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
35a0: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
35b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
35c0: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
35d0: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
35e0: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
35f0: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
3600: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
3610: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
3620: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
3630: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3640: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
3650: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
3660: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
3670: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
3680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
3690: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
36a0: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
36b0: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
36c0: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
36d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
36e0: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
36f0: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
3700: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
3710: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
3720: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
3730: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
3740: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
3750: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
3760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3770: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
3780: 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20     /* NOT USED. 
3790: 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20  Table or record 
37a0: 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65  not found */.#de
37b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
37c0: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
37d0: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
37e0: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
37f0: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
3800: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
3810: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
3820: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
3830: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
3840: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3850: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
3860: 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e  5   /* NOT USED.
3870: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70   Database lock p
3880: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f  rotocol error */
3890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38a0: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20  EMPTY       16  
38b0: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20   /* Database is 
38c0: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65  empty */.#define
38d0: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20   SQLITE_SCHEMA  
38e0: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20      17   /* The 
38f0: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
3900: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69  changed */.#defi
3910: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47  ne SQLITE_TOOBIG
3920: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74        18   /* St
3930: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63  ring or BLOB exc
3940: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20  eeds size limit 
3950: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3960: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39  E_CONSTRAINT  19
3970: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20     /* Abort due 
3980: 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69  to constraint vi
3990: 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69  olation */.#defi
39a0: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54  ne SQLITE_MISMAT
39b0: 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61  CH    20   /* Da
39c0: 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68  ta type mismatch
39d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
39e0: 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32  TE_MISUSE      2
39f0: 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75  1   /* Library u
3a00: 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  sed incorrectly 
3a10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3a20: 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32  E_NOLFS       22
3a30: 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65     /* Uses OS fe
3a40: 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f  atures not suppo
3a50: 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a  rted on host */.
3a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
3a70: 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20  UTH        23   
3a80: 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  /* Authorization
3a90: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
3aa0: 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54  ne SQLITE_FORMAT
3ab0: 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75        24   /* Au
3ac0: 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65  xiliary database
3ad0: 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f   format error */
3ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3af0: 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20  RANGE       25  
3b00: 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65   /* 2nd paramete
3b10: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
3b20: 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a  d out of range *
3b30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3b40: 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20  _NOTADB      26 
3b50: 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64    /* File opened
3b60: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64   that is not a d
3b70: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
3b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
3b90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
3ba0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
3bb0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
3bc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
3bd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
3be0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
3bf0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
3c00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
3c10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
3c20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
3c30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3c40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
3c50: 20 43 6f 64 65 73 20 7b 48 31 30 32 32 30 7d 20   Codes {H10220} 
3c60: 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S10700>.** KEYW
3c70: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
3c80: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
3c90: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
3ca0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
3cb0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
3cc0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
3cd0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
3ce0: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
3cf0: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
3d00: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
3d10: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
3d20: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
3d30: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
3d40: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
3d50: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
3d60: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
3d70: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
3d80: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
3d90: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
3da0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
3db0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
3dc0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
3dd0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
3de0: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
3df0: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
3e00: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
3e10: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
3e20: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
3e30: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
3e40: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
3e50: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
3e60: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
3e70: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
3e80: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
3e90: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
3ea0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
3eb0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
3ec0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
3ed0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
3ee0: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
3ef0: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
3f00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
3f10: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
3f20: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
3f30: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
3f40: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
3f50: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
3f60: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
3f70: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
3f80: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
3f90: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
3fa0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
3fb0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3fc0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
3fd0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
3fe0: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
3ff0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4000: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4010: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4020: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4030: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4040: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4050: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4060: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4070: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4080: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4090: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
40a0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
40b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
40c0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
40d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
40e0: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
40f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4100: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4110: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4120: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4130: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4140: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4150: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4160: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4170: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4180: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4190: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
41a0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
41b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
41c0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
41d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
41e0: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
41f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4200: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4210: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4220: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4230: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4240: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4250: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4260: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4270: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4280: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4290: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
42a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
42b0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
42c0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
42d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
42e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
42f0: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4300: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4310: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4320: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4330: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4340: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4350: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4360: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4370: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4380: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4390: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
43a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
43b0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
43c0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
43d0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
43e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
43f0: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4400: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4410: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4420: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4430: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4440: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4450: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4460: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4470: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4480: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4490: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
44a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
44b0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
44c0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
44d0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
44e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
44f0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4500: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4510: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 28 31 3c 3c  TE_LOCKED | (1<<
4520: 38 29 20 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  8) )../*.** CAPI
4530: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
4540: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
4550: 69 6f 6e 73 20 7b 48 31 30 32 33 30 7d 20 3c 48  ions {H10230} <H
4560: 31 31 31 32 30 3e 20 3c 48 31 32 37 30 30 3e 0a  11120> <H12700>.
4570: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20  **.** These bit 
4580: 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e  values are inten
4590: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74  ded for use in t
45a0: 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65  he.** 3rd parame
45b0: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
45c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
45d0: 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20  nterface and.** 
45e0: 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  in the 4th param
45f0: 65 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65  eter to the xOpe
4600: 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a  n method of the.
4610: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
4620: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
4630: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4640: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
4650: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
4660: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
4670: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
4680: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4690: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
46a0: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
46b0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
46c0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
46d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
46e0: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
46f0: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
4700: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
4710: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
4720: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4730: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
4740: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
4750: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
4760: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4770: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
4780: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
4790: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
47a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
47b0: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
47c0: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
47d0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
47e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
47f0: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
4800: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
4810: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
4820: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4830: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
4840: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
4850: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
4860: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4870: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
4880: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
4890: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
48a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
48b0: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
48c0: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
48d0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
48e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
48f0: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
4900: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
4910: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
4920: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4930: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
4940: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
4950: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
4960: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4970: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
4980: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
4990: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
49a0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
49b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
49c0: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
49d0: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
49e0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
49f0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
4a00: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4a10: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
4a20: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
4a30: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
4a40: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
4a50: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4a60: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
4a70: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
4a80: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
4a90: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a  pen_v2() */../*.
4aa0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
4ab0: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
4ac0: 69 63 73 20 7b 48 31 30 32 34 30 7d 20 3c 48 31  ics {H10240} <H1
4ad0: 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  1120>.**.** The 
4ae0: 78 44 65 76 69 63 65 43 61 70 61 62 69 6c 69 74  xDeviceCapabilit
4af0: 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ies method of th
4b00: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
4b10: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
4b20: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
4b30: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
4b40: 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65  ector of the the
4b50: 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73  se.** bit values
4b60: 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20   expressing I/O 
4b70: 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  characteristics 
4b80: 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72  of the mass stor
4b90: 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  age.** device th
4ba0: 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c  at holds the fil
4bb0: 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  e that the [sqli
4bc0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
4bd0: 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a  ** refers to..**
4be0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
4bf0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
4c00: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
4c10: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
4c20: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
4c30: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
4c40: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
4c50: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
4c60: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
4c70: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
4c80: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
4c90: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
4ca0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
4cb0: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
4cc0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
4cd0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
4ce0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
4cf0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
4d00: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
4d10: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
4d20: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
4d30: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
4d40: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
4d50: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
4d60: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
4d70: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
4d80: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
4d90: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
4da0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
4db0: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
4dc0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
4dd0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
4de0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
4df0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
4e00: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
4e10: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64   xWrite()..*/.#d
4e20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4e30: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
4e40: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
4e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4e60: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
4e70: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
4e80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4e90: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
4ea0: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
4eb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4ec0: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20  AP_ATOMIC2K     
4ed0: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
4ee0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4ef0: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
4f00: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
4f10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4f20: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
4f30: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
4f40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4f50: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
4f60: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
4f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4f80: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
4f90: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
4fa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4fb0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
4fc0: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
4fd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4fe0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
4ff0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
5000: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5010: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
5020: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f     0x00000400../
5030: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
5040: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
5050: 6c 73 20 7b 48 31 30 32 35 30 7d 20 3c 48 31 31  ls {H10250} <H11
5060: 31 32 30 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a  120> <H11310>.**
5070: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
5080: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
5090: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
50a0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
50b0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
50c0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
50d0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
50e0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
50f0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
5100: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
5110: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
5120: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
5130: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
5140: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
5150: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
5160: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5170: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
5180: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5190: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
51a0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
51b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
51c0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
51d0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
51e0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
51f0: 46 6c 61 67 73 20 7b 48 31 30 32 36 30 7d 20 3c  Flags {H10260} <
5200: 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68  H11120>.**.** Wh
5210: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5220: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5230: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5240: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5250: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5260: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5270: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5280: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5290: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
52a0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
52b0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
52c0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
52d0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
52e0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
52f0: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5300: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5310: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5320: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5330: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5340: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5350: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5360: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5370: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5380: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5390: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
53a0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
53b0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
53c0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
53d0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
53e0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
53f0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
5400: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
5410: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
5420: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
5430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5440: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
5450: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
5460: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
5470: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
5480: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
5490: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
54a0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
54b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
54c0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
54d0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 31   File Handle {H1
54e0: 31 31 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a  1110} <S20110>.*
54f0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
5500: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
5510: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
5520: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
5530: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
5540: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
5550: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
5560: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
5570: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
5580: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
5590: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
55a0: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
55b0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
55c0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
55d0: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
55e0: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
55f0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
5600: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
5610: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5620: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
5630: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
5640: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
5650: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
5660: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
5670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
5680: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
5690: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
56a0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
56b0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
56c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
56d0: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
56e0: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
56f0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
5700: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
5710: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
5720: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
5730: 62 6a 65 63 74 20 7b 48 31 31 31 32 30 7d 20 3c  bject {H11120} <
5740: 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 45 76  S20110>.**.** Ev
5750: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
5760: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
5770: 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f  vfs] xOpen metho
5780: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
5790: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
57a0: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
57b0: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
57c0: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
57d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
57e0: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
57f0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
5800: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
5810: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
5820: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
5830: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
5840: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
5850: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
5860: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
5870: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
5880: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
5890: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
58a0: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65  *.** If the xOpe
58b0: 6e 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  n method sets th
58c0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
58d0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
58e0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
58f0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
5900: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
5910: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
5920: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
5930: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
5940: 68 65 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65  he xOpen reporte
5950: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
5960: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
5970: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
5980: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
5990: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
59a0: 64 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f  d xOpen.** is fo
59b0: 72 20 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73  r the xOpen to s
59c0: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
59d0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
59e0: 6d 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  ment to NULL..**
59f0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
5a00: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
5a10: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
5a20: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
5a30: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
5a40: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
5a50: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
5a60: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
5a70: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nc()..** The sec
5a80: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20  ond choice is a 
5a90: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
5aa0: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53  ullsync.  The [S
5ab0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
5ac0: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79  NLY].** flag may
5ad0: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69   be ORed in to i
5ae0: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c  ndicate that onl
5af0: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68  y the data of th
5b00: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f  e file.** and no
5b10: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64  t its inode need
5b20: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a  s to be synced..
5b30: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65  **.** The intege
5b40: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63  r values to xLoc
5b50: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
5b60: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  ) are one of.** 
5b70: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
5b80: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
5b90: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5ba0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
5bb0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
5bc0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a  OCK_RESERVED],.*
5bd0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
5be0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
5bf0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5c00: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
5c10: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c  ..** </ul>.** xL
5c20: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20  ock() increases 
5c30: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63  the lock. xUnloc
5c40: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68  k() decreases th
5c50: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78  e lock..** The x
5c60: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
5c70: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b  k() method check
5c80: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61  s whether any da
5c90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
5ca0: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20  n,.** either in 
5cb0: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20  this process or 
5cc0: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
5cd0: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
5ce0: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a  g a RESERVED,.**
5cf0: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
5d00: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
5d10: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
5d20: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
5d30: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
5d40: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68  ts and false oth
5d50: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erwise..**.** Th
5d60: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
5d70: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
5d80: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
5d90: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
5da0: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
5db0: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
5dc0: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
5dd0: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
5de0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
5df0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
5e00: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
5e10: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
5e20: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e  ment is an.** in
5e30: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54  teger opcode.  T
5e40: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
5e50: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70  t is a generic p
5e60: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20  ointer intended 
5e70: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  to.** point to a
5e80: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
5e90: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75  may contain argu
5ea0: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69  ments or space i
5eb0: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72  n which to.** wr
5ec0: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ite return value
5ed0: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73  s.  Potential us
5ee0: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74  es for xFileCont
5ef0: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a  rol() might be.*
5f00: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65  * functions to e
5f10: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c  nable blocking l
5f20: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75  ocks with timeou
5f30: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ts, to change th
5f40: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72  e.** locking str
5f50: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70  ategy (for examp
5f60: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69  le to use dot-fi
5f70: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e  le locks), to in
5f80: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74  quire.** about t
5f90: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c  he status of a l
5fa0: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b  ock, or to break
5fb0: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54   stale locks.  T
5fc0: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72  he SQLite.** cor
5fd0: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f  e reserves all o
5fe0: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
5ff0: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
6000: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49   use..** A [SQLI
6010: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
6020: 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63  TE | list of opc
6030: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20  odes] less than 
6040: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65  100 is available
6050: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
6060: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20  s that define a 
6070: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74  custom xFileCont
6080: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  rol method shoul
6090: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a  d use opcodes.**
60a0: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30   greater than 10
60b0: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c  0 to avoid confl
60c0: 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  icts..**.** The 
60d0: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65  xSectorSize() me
60e0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65  thod returns the
60f0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20   sector size of 
6100: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  the.** device th
6110: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65  at underlies the
6120: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74   file.  The sect
6130: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a  or size is the.*
6140: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20  * minimum write 
6150: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66  that can be perf
6160: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69  ormed without di
6170: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65  sturbing.** othe
6180: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  r bytes in the f
6190: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63  ile.  The xDevic
61a0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
61b0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
61c0: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f  urns a bit vecto
61d0: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68  r describing beh
61e0: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a  aviors of the.**
61f0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69   underlying devi
6200: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce:.**.** <ul>.*
6210: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6220: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20  OCAP_ATOMIC].** 
6230: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6240: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a  AP_ATOMIC512].**
6250: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6260: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a  CAP_ATOMIC1K].**
6270: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6280: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a  CAP_ATOMIC2K].**
6290: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
62a0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a  CAP_ATOMIC4K].**
62b0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
62c0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a  CAP_ATOMIC8K].**
62d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
62e0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a  CAP_ATOMIC16K].*
62f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6300: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a  OCAP_ATOMIC32K].
6310: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6320: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d  IOCAP_ATOMIC64K]
6330: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6340: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6350: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ND].** <li> [SQL
6360: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6370: 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  TIAL].** </ul>.*
6380: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
6390: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
63a0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
63b0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
63c0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
63d0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
63e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
63f0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
6400: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
6410: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
6420: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
6430: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
6440: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
6450: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
6460: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
6470: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
6480: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6490: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
64a0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
64b0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
64c0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
64d0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
64e0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
64f0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
6500: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
6510: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
6520: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
6530: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
6540: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6550: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
6560: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6570: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
6580: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
6590: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
65a0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
65b0: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
65c0: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
65d0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
65e0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
65f0: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
6600: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
6610: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
6620: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
6630: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
6640: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
6650: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
6660: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
6670: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
6680: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
6690: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
66a0: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
66b0: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
66c0: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
66d0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
66e0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
66f0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
6700: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
6710: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
6720: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
6730: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
6740: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
6750: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
6760: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
6770: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
6780: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
6790: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
67a0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
67b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
67c0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
67d0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
67e0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
67f0: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
6800: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
6810: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
6820: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
6830: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
6840: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
6850: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
6860: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
6870: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
6880: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
6890: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
68a0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
68b0: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
68c0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
68d0: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
68e0: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
68f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
6900: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
6910: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
6920: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
6930: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
6940: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
6950: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
6960: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
6970: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6980: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
6990: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74  le*);.  /* Addit
69a0: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61  ional methods ma
69b0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
69c0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f  ture releases */
69d0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
69e0: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69  REF: Standard Fi
69f0: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64  le Control Opcod
6a00: 65 73 20 7b 48 31 31 33 31 30 7d 20 3c 53 33 30  es {H11310} <S30
6a10: 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  800>.**.** These
6a20: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
6a30: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
6a40: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
6a50: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
6a60: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6a70: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6a80: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
6a90: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
6aa0: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
6ab0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
6ac0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
6ad0: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
6ae0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
6af0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
6b00: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
6b10: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
6b20: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
6b30: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
6b40: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
6b50: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
6b60: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
6b70: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
6b80: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
6b90: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
6ba0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
6bb0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
6bc0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
6bd0: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
6be0: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
6bf0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
6c00: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
6c10: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
6c20: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
6c30: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
6c40: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
6c50: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
6c60: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23  is defined..*/.#
6c70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
6c80: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
6c90: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
6ca0: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
6cb0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23  OXYFILE      2.#
6cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
6cd0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
6ce0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6cf0: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
6d00: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 0a               4..
6d10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6d20: 4d 75 74 65 78 20 48 61 6e 64 6c 65 20 7b 48 31  Mutex Handle {H1
6d30: 37 31 31 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a  7110} <S20130>.*
6d40: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
6d50: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
6d60: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
6d70: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
6d80: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
6d90: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
6da0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
6db0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
6dc0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
6dd0: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
6de0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
6df0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
6e00: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
6e10: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
6e20: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
6e30: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
6e40: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
6e50: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
6e60: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
6e70: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
6e80: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
6e90: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
6ea0: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
6eb0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
6ec0: 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 48 31 31  face Object {H11
6ed0: 31 34 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a  140} <S20100>.**
6ee0: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
6ef0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
6f00: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
6f10: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
6f20: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
6f30: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
6f40: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
6f50: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
6f60: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
6f70: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
6f80: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
6f90: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
6fa0: 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20   system"..**.** 
6fb0: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  The value of the
6fc0: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
6fd0: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
6fe0: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
6ff0: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65   in.** future ve
7000: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
7010: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
7020: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
7030: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
7040: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
7050: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
7060: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f  s increased.  No
7070: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
7080: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
7090: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
70a0: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
70b0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
70c0: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  tween.** SQLite 
70d0: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e  version 3.5.9 an
70e0: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20  d 3.6.0 and yet 
70f0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
7100: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f  ld was not.** mo
7110: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
7120: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
7130: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
7140: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
7150: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
7160: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
7170: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
7180: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
7190: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
71a0: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
71b0: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
71c0: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
71d0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
71e0: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
71f0: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
7200: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
7210: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
7220: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
7230: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
7240: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
7250: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
7260: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
7270: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
7280: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
7290: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
72a0: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
72b0: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
72c0: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
72d0: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
72e0: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
72f0: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
7300: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
7310: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
7320: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
7330: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
7340: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
7350: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
7360: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
7370: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
7380: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
7390: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
73a0: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
73b0: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
73c0: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
73d0: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
73e0: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
73f0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
7400: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
7410: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
7420: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
7430: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
7440: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
7450: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
7460: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
7470: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
7480: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
7490: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
74a0: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
74b0: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
74c0: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  dules..**.** SQL
74d0: 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74  ite will guarant
74e0: 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  ee that the zFil
74f0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
7500: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
7510: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
7520: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
7530: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
7540: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e  xFullPathname().
7550: 20 20 53 51 4c 69 74 65 20 66 75 72 74 68 65 72    SQLite further
7560: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
7570: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
7580: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
7590: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
75a0: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
75b0: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
75c0: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
75d0: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
75e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
75f0: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
7600: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
7610: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
7620: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
7630: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
7640: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
7650: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
7660: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
7670: 72 20 69 73 20 78 4f 70 65 6e 20 69 73 20 61 20  r is xOpen is a 
7680: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
7690: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
76a0: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
76b0: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
76c0: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 57 68 65  r the file.  Whe
76d0: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
76e0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
76f0: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
7700: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
7710: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
7720: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
7730: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
7740: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
7750: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
7760: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
7770: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
7780: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
7790: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
77a0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
77b0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
77c0: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
77d0: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
77e0: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
77f0: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
7800: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
7810: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
7820: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
7830: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
7840: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
7850: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
7860: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
7870: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
7880: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
7890: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
78a0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
78b0: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
78c0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
78d0: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51  be set..**.** SQ
78e0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
78f0: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
7900: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
7910: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
7920: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
7930: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
7940: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
7950: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
7960: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
7970: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
7980: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
7990: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
79a0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
79b0: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
79c0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
79d0: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
79e0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
79f0: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
7a00: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7a10: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
7a20: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
7a30: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
7a40: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  JOURNAL].** </ul
7a50: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  >.**.** The file
7a60: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
7a70: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
7a80: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
7a90: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
7aa0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
7ab0: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
7ac0: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
7ad0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
7ae0: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
7af0: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
7b00: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
7b10: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
7b20: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
7b30: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
7b40: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
7b50: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
7b60: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
7b70: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
7b80: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
7b90: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
7ba0: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
7bb0: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
7bc0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
7bd0: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
7be0: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
7bf0: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
7c00: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
7c10: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
7c20: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
7c30: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
7c40: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
7c50: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
7c60: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
7c70: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
7c80: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
7c90: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
7ca0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
7cb0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
7cc0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
7cd0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
7ce0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7cf0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
7d00: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
7d10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
7d20: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
7d30: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
7d40: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
7d50: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
7d60: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 54 68 65   is closed.  The
7d70: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
7d80: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
7d90: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
7da0: 54 45 4d 50 20 20 64 61 74 61 62 61 73 65 73 2c  TEMP  databases,
7db0: 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f   journals and fo
7dc0: 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  r subjournals..*
7dd0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7de0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
7df0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
7e00: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
7e10: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
7e20: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
7e30: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
7e40: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
7e50: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
7e60: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
7e70: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
7e80: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
7e90: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
7ea0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
7eb0: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
7ec0: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
7ed0: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
7ee0: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
7ef0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
7f00: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
7f10: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
7f20: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
7f30: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
7f40: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
7f50: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
7f60: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
7f70: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
7f80: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
7f90: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
7fa0: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
7fb0: 2a 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46  * At least szOsF
7fc0: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
7fd0: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
7fe0: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
7ff0: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
8000: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
8010: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
8020: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
8030: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
8040: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
8050: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
8060: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
8070: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
8080: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
8090: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
80a0: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
80b0: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
80c0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
80d0: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
80e0: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
80f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8100: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
8110: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
8120: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
8130: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
8140: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
8150: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
8160: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
8170: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
8180: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
8190: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
81a0: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
81b0: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
81c0: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
81d0: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
81e0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
81f0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
8200: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
8210: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
8220: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
8230: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
8240: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
8250: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
8260: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
8270: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
8280: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
8290: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
82a0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
82b0: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
82c0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
82d0: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
82e0: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
82f0: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
8300: 72 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ry..**.** SQLite
8310: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
8320: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
8330: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
8340: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
8350: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
8360: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
8370: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
8380: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
8390: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
83a0: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
83b0: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
83c0: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
83d0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
83e0: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
83f0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
8400: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
8410: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
8420: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
8430: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
8440: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
8450: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
8460: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
8470: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
8480: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
8490: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
84a0: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
84b0: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
84c0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
84d0: 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75  Sleep(), and xCu
84e0: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65  rrentTime() inte
84f0: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
8500: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
8510: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
8520: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
8530: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
8540: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
8550: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
8560: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
8570: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
8580: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
8590: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
85a0: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
85b0: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
85c0: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
85d0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
85e0: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
85f0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
8600: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
8610: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
8620: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
8630: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
8640: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
8650: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
8660: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
8670: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
8680: 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e 74  n.  The xCurrent
8690: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
86a0: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
86b0: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
86c0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
86d0: 65 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  e and time..**.*
86e0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
86f0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
8700: 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74  ite3_vfs;.struct
8710: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
8720: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
8730: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
8740: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
8750: 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73  umber */.  int s
8760: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
8770: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
8780: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
8790: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
87a0: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
87b0: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
87c0: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
87d0: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
87e0: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
87f0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
8800: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
8810: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
8820: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
8830: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
8840: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
8850: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
8860: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
8870: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
8880: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
8890: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
88a0: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
88b0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
88c0: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
88d0: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
88e0: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
88f0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
8900: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
8910: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
8920: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
8930: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
8940: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
8950: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
8960: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
8970: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
8980: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
8990: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
89a0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
89b0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
89c0: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
89d0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
89e0: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
89f0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
8a00: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
8a10: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
8a20: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
8a30: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
8a40: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
8a50: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
8a60: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
8a70: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
8a80: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
8a90: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
8aa0: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
8ab0: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
8ac0: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
8ad0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
8ae0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
8af0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
8b00: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
8b10: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
8b20: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
8b30: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
8b40: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
8b50: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
8b60: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
8b70: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
8b80: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65  char *);.  /* Ne
8b90: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
8ba0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
8bb0: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
8bc0: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
8bd0: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
8be0: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
8bf0: 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d  is happens. */.}
8c00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8c10: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
8c20: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
8c30: 68 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31  hod {H11190} <H1
8c40: 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  1140>.**.** Thes
8c50: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
8c60: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
8c70: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
8c80: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
8c90: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
8ca0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
8cb0: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44  fs] object. {END
8cc0: 7d 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  }  They determin
8cd0: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
8ce0: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
8cf0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
8d00: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
8d10: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
8d20: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
8d30: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
8d40: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
8d50: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
8d60: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
8d70: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
8d80: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
8d90: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
8da0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
8db0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f  r the file is bo
8dc0: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
8dd0: 77 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74  writable..** Wit
8de0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
8df0: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
8e00: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
8e10: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
8e20: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
8e30: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
8e40: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
8e50: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
8e60: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
8e70: 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20  WRITE 1.#define 
8e80: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
8e90: 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a  AD      2../*.**
8ea0: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
8eb0: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
8ec0: 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33 30   Library {H10130
8ed0: 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30  } <S20000><S3010
8ee0: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
8ef0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8f00: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
8f10: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
8f20: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
8f30: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
8f40: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
8f50: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
8f60: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
8f70: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
8f80: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8f90: 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  ize()..**.** A c
8fa0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
8fb0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
8fc0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
8fd0: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
8fe0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
8ff0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9000: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
9010: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
9020: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
9030: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
9040: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
9050: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9060: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
9070: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
9080: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
9090: 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79  hutdown().  Only
90a0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
90b0: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
90c0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
90d0: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
90e0: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
90f0: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
9100: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a  armless no-ops..
9110: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
9120: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
9130: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
9140: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
9150: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
9160: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
9170: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
9180: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
9190: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
91a0: 20 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65   Only.** an effe
91b0: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
91c0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
91d0: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
91e0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
91f0: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 20 74  ll other calls t
9200: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
9210: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
9220: 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20  s no-ops..**.** 
9230: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
9240: 67 73 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  gs, sqlite3_init
9250: 69 61 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20 69  ialize() shall i
9260: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
9270: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
9280: 69 6c 61 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f  ilarly, sqlite3_
9290: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68  shutdown().** sh
92a0: 61 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  all invoke sqlit
92b0: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
92c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
92d0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
92e0: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
92f0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
9300: 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f  ss..** If for so
9310: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
9320: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9330: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
9340: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
9350: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
9360: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
9370: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
9380: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
9390: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
93a0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
93b0: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
93c0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
93d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
93e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
93f0: 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
9400: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9410: 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53   many other.** S
9420: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
9430: 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c   so that an appl
9440: 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20  ication usually 
9450: 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
9460: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
9470: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9480: 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65  directly.  For e
9490: 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33  xample, [sqlite3
94a0: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c  _open()].** call
94b0: 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
94c0: 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51  lize() so the SQ
94d0: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
94e0: 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
94f0: 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65  ly.** initialize
9500: 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
9510: 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65  open()] is calle
9520: 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20  d if it has not 
9530: 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a  be initialized.*
9540: 2a 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77 65  * already.  Howe
9550: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
9560: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
9570: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
9580: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
9590: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
95a0: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
95b0: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
95c0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
95d0: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
95e0: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
95f0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
9600: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9610: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
9620: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
9630: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
9640: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
9650: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
9660: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
9670: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
9680: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
9690: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
96a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
96b0: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
96c0: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
96d0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
96e0: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
96f0: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
9700: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
9710: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
9720: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
9730: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
9740: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
9750: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
9760: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
9770: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
9780: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
9790: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
97a0: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
97b0: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
97c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
97d0: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
97e0: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
97f0: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
9800: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
9810: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
9820: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
9830: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
9840: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
9850: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
9860: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9870: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
9880: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
9890: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
98a0: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
98b0: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
98c0: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
98d0: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
98e0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
98f0: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
9900: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
9910: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
9920: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
9930: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
9940: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
9950: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
9960: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
9970: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
9980: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
9990: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
99a0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
99b0: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
99c0: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
99d0: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
99e0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
99f0: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
9a00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9a10: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
9a20: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
9a30: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
9a40: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
9a50: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
9a60: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
9a70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
9a80: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
9a90: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
9aa0: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
9ab0: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
9ac0: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
9ad0: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
9ae0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
9af0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9b00: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
9b10: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
9b20: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
9b30: 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
9b40: 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
9b50: 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
9b60: 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
9b70: 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
9b80: 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
9b90: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
9ba0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
9bb0: 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
9bc0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
9bd0: 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
9be0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
9bf0: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
9c00: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
9c10: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
9c20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
9c30: 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
9c40: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
9c50: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
9c60: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9c70: 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
9c80: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
9c90: 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
9ca0: 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
9cb0: 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
9cc0: 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
9cd0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
9ce0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
9cf0: 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
9d00: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
9d10: 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
9d20: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
9d30: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
9d40: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
9d50: 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
9d60: 62 72 61 72 79 20 7b 48 31 34 31 30 30 7d 20 3c  brary {H14100} <
9d70: 53 32 30 30 30 30 3e 3c 53 33 30 32 30 30 3e 0a  S20000><S30200>.
9d80: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
9d90: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
9da0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
9db0: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
9dc0: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
9dd0: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
9de0: 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
9df0: 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
9e00: 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
9e10: 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
9e20: 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
9e30: 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
9e40: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
9e50: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
9e60: 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
9e70: 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
9e80: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
9e90: 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
9ea0: 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
9eb0: 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
9ec0: 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
9ed0: 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
9ee0: 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
9ef0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
9f00: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
9f10: 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
9f20: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
9f30: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
9f40: 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
9f50: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
9f60: 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
9f70: 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
9f80: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
9f90: 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
9fa0: 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
9fb0: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
9fc0: 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
9fd0: 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
9fe0: 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
9ff0: 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
a000: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
a010: 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
a020: 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
a030: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a040: 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  ()]..** Note, ho
a050: 77 65 76 65 72 2c 20 74 68 61 74 20 73 71 6c 69  wever, that sqli
a060: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
a070: 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
a080: 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
a090: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
a0a0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
a0b0: 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
a0c0: 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
a0d0: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
a0e0: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
a0f0: 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
a100: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  teger.** [SQLITE
a110: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
a120: 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61  READ | configura
a130: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
a140: 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
a150: 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
a160: 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
a170: 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
a180: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
a190: 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
a1a0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c  ding on the [SQL
a1b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
a1c0: 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67  ETHREAD | config
a1d0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
a1e0: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
a1f0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
a200: 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
a210: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
a220: 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
a230: 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
a240: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 49 66 20  LITE_OK]..** If 
a250: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
a260: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
a270: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
a280: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
a290: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
a2a0: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
a2b0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
a2c0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
a2d0: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 31 30 33  ents:.** [H14103
a2e0: 5d 20 5b 48 31 34 31 30 36 5d 20 5b 48 31 34 31  ] [H14106] [H141
a2f0: 32 30 5d 20 5b 48 31 34 31 32 33 5d 20 5b 48 31  20] [H14123] [H1
a300: 34 31 32 36 5d 20 5b 48 31 34 31 32 39 5d 20 5b  4126] [H14129] [
a310: 48 31 34 31 33 32 5d 20 5b 48 31 34 31 33 35 5d  H14132] [H14135]
a320: 0a 2a 2a 20 5b 48 31 34 31 33 38 5d 20 5b 48 31  .** [H14138] [H1
a330: 34 31 34 31 5d 20 5b 48 31 34 31 34 34 5d 20 5b  4141] [H14144] [
a340: 48 31 34 31 34 37 5d 20 5b 48 31 34 31 35 30 5d  H14147] [H14150]
a350: 20 5b 48 31 34 31 35 33 5d 20 5b 48 31 34 31 35   [H14153] [H1415
a360: 36 5d 20 5b 48 31 34 31 35 39 5d 0a 2a 2a 20 5b  6] [H14159].** [
a370: 48 31 34 31 36 32 5d 20 5b 48 31 34 31 36 35 5d  H14162] [H14165]
a380: 20 5b 48 31 34 31 36 38 5d 0a 2a 2f 0a 53 51 4c   [H14168].*/.SQL
a390: 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
a3a0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e   int sqlite3_con
a3b0: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
a3c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a3d0: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
a3e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20  se connections  
a3f0: 7b 48 31 34 32 30 30 7d 20 3c 53 32 30 30 30 30  {H14200} <S20000
a400: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
a410: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  L.**.** The sqli
a420: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
a430: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
a440: 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67  d to make config
a450: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
a460: 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73  es to a [databas
a470: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
a480: 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73  The interface is
a490: 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b   similar to.** [
a4a0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a4b0: 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
a4c0: 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20  e changes apply 
a4d0: 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  to a single.** [
a4e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a4f0: 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20  ion] (specified 
a500: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
a510: 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20  ument).  The.** 
a520: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
a530: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
a540: 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69  n only be used i
a550: 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
a560: 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
a570: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
a580: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
a590: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a  lite3_open()],.*
a5a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
a5b0: 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  6()], or [sqlite
a5c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a  3_open_v2()].  .
a5d0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
a5e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
a5f0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
a600: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
a610: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
a620: 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67   verb - an integ
a630: 65 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64  er code that ind
a640: 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61  icates what.** a
a650: 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
a660: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
a670: 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
a680: 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f  igured..** The o
a690: 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74  nly choice for t
a6a0: 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51  his value is [SQ
a6b0: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
a6c0: 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77  OKASIDE]..** New
a6d0: 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c   verbs are likel
a6e0: 79 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e  y to be added in
a6f0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
a700: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41   of SQLite..** A
a710: 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
a720: 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68  nts depend on th
a730: 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 52 65  e verb..**.** Re
a740: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
a750: 48 31 34 32 30 33 5d 20 5b 48 31 34 32 30 36 5d  H14203] [H14206]
a760: 20 5b 48 31 34 32 30 39 5d 20 5b 48 31 34 32 31   [H14209] [H1421
a770: 32 5d 20 5b 48 31 34 32 31 35 5d 0a 2a 2f 0a 53  2] [H14215].*/.S
a780: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
a790: 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  AL int sqlite3_d
a7a0: 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
a7b0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
a7c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a7d0: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
a7e0: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31  ion Routines {H1
a7f0: 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a  0155} <S20120>.*
a800: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
a810: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
a820: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
a830: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
a840: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
a850: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
a860: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
a870: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
a880: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
a890: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
a8a0: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
a8b0: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
a8c0: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
a8d0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
a8e0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
a8f0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
a900: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
a910: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
a920: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
a930: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
a940: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
a950: 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
a960: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
a970: 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
a980: 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
a990: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
a9a0: 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
a9b0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
a9c0: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
a9d0: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
a9e0: 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
a9f0: 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
aa00: 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
aa10: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
aa20: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
aa30: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
aa40: 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
aa50: 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
aa60: 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
aa70: 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
aa80: 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
aa90: 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
aaa0: 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
aab0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
aac0: 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
aad0: 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
aae0: 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
aaf0: 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
ab00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
ab10: 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
ab20: 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
ab30: 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
ab40: 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
ab50: 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
ab60: 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
ab70: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
ab80: 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
ab90: 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
aba0: 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
abb0: 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
abc0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
abd0: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
abe0: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
abf0: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
ac00: 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
ac10: 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
ac20: 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
ac30: 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
ac40: 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
ac50: 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
ac60: 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
ac70: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
ac80: 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78 46 72   xMalloc and xFr
ac90: 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
aca0: 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
acb0: 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
acc0: 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
acd0: 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
ace0: 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54   C library..** T
acf0: 68 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68  he xRealloc meth
ad00: 6f 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  od must work lik
ad10: 65 20 72 65 61 6c 6c 6f 63 28 29 20 66 72 6f 6d  e realloc() from
ad20: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
ad30: 6c 69 62 72 61 72 79 0a 2a 2a 20 77 69 74 68 20  library.** with 
ad40: 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74 68  the exception th
ad50: 61 74 20 69 66 20 74 68 65 20 73 65 63 6f 6e 64  at if the second
ad60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 52 65   argument to xRe
ad70: 61 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c 0a 2a  alloc is zero,.*
ad80: 2a 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73 74 20  * xRealloc must 
ad90: 62 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 20  be a no-op - it 
ada0: 6d 75 73 74 20 6e 6f 74 20 70 65 72 66 6f 72 6d  must not perform
adb0: 20 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20   any allocation 
adc0: 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 69  or.** deallocati
add0: 6f 6e 2e 20 20 53 51 4c 69 74 65 20 67 75 61 72  on.  SQLite guar
ade0: 61 6e 74 65 65 64 73 20 74 68 61 74 20 74 68 65  anteeds that the
adf0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
ae00: 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
ae10: 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
ae20: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
ae30: 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
ae40: 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 73  oundup..** And s
ae50: 6f 20 69 6e 20 63 61 73 65 73 20 77 68 65 72 65  o in cases where
ae60: 20 78 52 6f 75 6e 64 75 70 20 61 6c 77 61 79 73   xRoundup always
ae70: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74   returns a posit
ae80: 69 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78  ive number,.** x
ae90: 52 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65 72 66  Realloc can perf
aea0: 6f 72 6d 20 65 78 61 63 74 6c 79 20 61 73 20 74  orm exactly as t
aeb0: 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72  he standard libr
aec0: 61 72 79 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  ary realloc() an
aed0: 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20 69 6e  d.** still be in
aee0: 20 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69 74 68   compliance with
aef0: 20 74 68 69 73 20 73 70 65 63 69 66 69 63 61 74   this specificat
af00: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  ion..**.** xSize
af10: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
af20: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
af30: 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
af40: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
af50: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
af60: 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
af70: 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
af80: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
af90: 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
afa0: 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
afb0: 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
afc0: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
afd0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
afe0: 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
aff0: 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
b000: 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
b010: 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
b020: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b030: 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
b040: 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
b050: 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
b060: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
b070: 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
b080: 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
b090: 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
b0a0: 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
b0b0: 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
b0c0: 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
b0d0: 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
b0e0: 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
b0f0: 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
b100: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b110: 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
b120: 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
b130: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
b140: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
b150: 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
b160: 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
b170: 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
b180: 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
b190: 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
b1a0: 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
b1b0: 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
b1c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
b1d0: 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
b1e0: 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
b1f0: 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
b200: 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
b210: 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
b220: 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
b230: 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
b240: 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
b250: 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
b260: 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
b270: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
b280: 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
b290: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
b2a0: 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
b2b0: 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
b2c0: 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
b2d0: 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
b2e0: 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
b2f0: 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
b300: 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
b310: 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
b320: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
b330: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
b340: 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
b350: 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
b360: 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
b370: 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
b380: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
b390: 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
b3a0: 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
b3b0: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
b3c0: 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
b3d0: 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
b3e0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b3f0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
b400: 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
b410: 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
b420: 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
b430: 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
b440: 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
b450: 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
b460: 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
b470: 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
b480: 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
b490: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
b4a0: 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
b4b0: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
b4c0: 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
b4d0: 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
b4e0: 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
b4f0: 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
b500: 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
b510: 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
b520: 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
b530: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
b540: 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
b550: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
b560: 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
b570: 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
b580: 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
b590: 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
b5a0: 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
b5b0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
b5c0: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
b5d0: 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
b5e0: 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
b5f0: 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
b600: 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
b610: 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
b620: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
b630: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
b640: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
b650: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
b660: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
b670: 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
b680: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
b690: 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
b6a0: 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
b6b0: 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
b6c0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
b6d0: 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
b6e0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
b6f0: 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
b700: 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
b710: 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
b720: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
b730: 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
b740: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
b750: 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
b760: 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
b770: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
b780: 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
b790: 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
b7a0: 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
b7b0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
b7c0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
b7d0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
b7e0: 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
b7f0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
b800: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
b810: 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
b820: 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
b830: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
b840: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
b850: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
b860: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
b870: 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
b880: 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
b890: 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
b8a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b8b0: 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
b8c0: 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d  Options {H10160}
b8d0: 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50   <S20000>.** EXP
b8e0: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
b8f0: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
b900: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
b910: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
b920: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
b930: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
b940: 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
b950: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
b960: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
b970: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
b980: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
b990: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
b9a0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
b9b0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
b9c0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
b9d0: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
b9e0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
b9f0: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
ba00: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
ba10: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
ba20: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
ba30: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
ba40: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
ba50: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
ba60: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
ba70: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
ba80: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
ba90: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
baa0: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
bab0: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
bac0: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
bad0: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
bae0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
baf0: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
bb00: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
bb10: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
bb20: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
bb30: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
bb40: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
bb50: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
bb60: 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61  This option disa
bb70: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
bb80: 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
bb90: 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
bba0: 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
bbb0: 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
bbc0: 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
bbd0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
bbe0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
bbf0: 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
bc00: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
bc10: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
bc20: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54   this option.  T
bc30: 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62  his option disab
bc40: 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
bc50: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
bc60: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
bc70: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
bc80: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
bc90: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
bca0: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
bcb0: 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
bcc0: 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
bcd0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
bce0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
bcf0: 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
bd00: 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
bd10: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
bd20: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
bd30: 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
bd40: 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
bd50: 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
bd60: 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
bd70: 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
bd80: 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
bd90: 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
bda0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
bdb0: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
bdc0: 20 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61    See the [threa
bdd0: 64 69 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 6f  ding mode].** do
bde0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
bdf0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
be00: 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  mation.</dd>.**.
be10: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
be20: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
be30: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
be40: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
be50: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
be60: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
be70: 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
be80: 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
be90: 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
bea0: 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
beb0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
bec0: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
bed0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
bee0: 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
bef0: 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
bf00: 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
bf10: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
bf20: 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
bf30: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
bf40: 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
bf50: 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
bf60: 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
bf70: 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
bf80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
bf90: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
bfa0: 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
bfb0: 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
bfc0: 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
bfd0: 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
bfe0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bff0: 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
c000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
c010: 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
c020: 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
c030: 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
c040: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  See the [threadi
c050: 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e  ng mode] documen
c060: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
c070: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
c080: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
c090: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c0a0: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
c0b0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
c0c0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
c0d0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
c0e0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
c0f0: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
c100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
c110: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
c120: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
c130: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
c140: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
c150: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
c160: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
c170: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
c180: 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
c190: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c1a0: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
c1b0: 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  nto SQLite.</dd>
c1c0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c1d0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
c1e0: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OC</dt>.** <dd>T
c1f0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
c200: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
c210: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
c220: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
c230: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
c240: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
c250: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
c260: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
c270: 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
c280: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
c290: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
c2a0: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
c2b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
c2c0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73  outines..** This
c2d0: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
c2e0: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
c2f0: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
c300: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
c310: 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
c320: 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
c330: 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
c340: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
c350: 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
c360: 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
c370: 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e  or example.</dd>
c380: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c390: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
c3a0: 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  US</dt>.** <dd>T
c3b0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
c3c0: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
c3d0: 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e   of type int, in
c3e0: 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a  terpreted as a .
c3f0: 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63  ** boolean, whic
c400: 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
c410: 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
c420: 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61  tion of memory a
c430: 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74  llocation .** st
c440: 61 74 69 73 74 69 63 73 2e 20 57 68 65 6e 20 64  atistics. When d
c450: 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c  isabled, the fol
c460: 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
c470: 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
c480: 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  .** non-operatio
c490: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
c4a0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
c4b0: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
c4c0: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
c4d0: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
c4e0: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
c4f0: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
c500: 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  heap_limit()].**
c510: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
c520: 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20  _status()].**   
c530: 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  </ul>.** </dd>.*
c540: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
c550: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
c560: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
c570: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
c580: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
c590: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
c5a0: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
c5b0: 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
c5c0: 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68  y.  There are th
c5d0: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20  ree arguments:  
c5e0: 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62  A pointer an 8-b
c5f0: 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d  yte.** aligned m
c600: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f  emory buffer fro
c610: 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61  m which the scra
c620: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
c630: 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
c640: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
c650: 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
c660: 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
c670: 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
c680: 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
c690: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
c6a0: 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
c6b0: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
c6c0: 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54  ultiple of 16. T
c6d0: 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20  he sz parameter 
c6e0: 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20  should be a few 
c6f0: 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20  bytes.** larger 
c700: 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20  than the actual 
c710: 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65  scratch space re
c720: 71 75 69 72 65 64 20 64 75 65 20 74 6f 20 69 6e  quired due to in
c730: 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e  ternal overhead.
c740: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
c750: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
c760: 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
c770: 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
c780: 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
c790: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
c7a0: 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65  emory..** SQLite
c7b0: 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
c7c0: 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
c7d0: 63 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e 63  ch buffer at onc
c7e0: 65 20 70 65 72 20 74 68 72 65 61 64 2c 20 73 6f  e per thread, so
c7f0: 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20  .** N should be 
c800: 73 65 74 20 74 6f 20 74 68 65 20 65 78 70 65 63  set to the expec
c810: 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ted maximum numb
c820: 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20  er of threads.  
c830: 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65  The sz.** parame
c840: 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36 20  ter should be 6 
c850: 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20 6f  times the size o
c860: 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
c870: 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
c880: 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75 66  ..** Scratch buf
c890: 66 65 72 73 20 61 72 65 20 75 73 65 64 20 61 73  fers are used as
c8a0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 74 72   part of the btr
c8b0: 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 61  ee balance opera
c8c0: 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65  tion.  If.** The
c8d0: 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72 20   btree balancer 
c8e0: 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
c8f0: 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
c900: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
c910: 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 75  by.** scratch bu
c920: 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 73  ffers or if no s
c930: 63 72 61 74 63 68 20 62 75 66 66 65 72 20 73 70  cratch buffer sp
c940: 61 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64  ace is specified
c950: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
c960: 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
c970: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f  3_malloc()] to o
c980: 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
c990: 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a   it needs.</dd>.
c9a0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
c9b0: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
c9c0: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  E</dt>.** <dd>Th
c9d0: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
c9e0: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
c9f0: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
ca00: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
ca10: 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
ca20: 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
ca30: 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
ca40: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
ca50: 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  enation.  .** Th
ca60: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
ca70: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
ca80: 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
ca90: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
caa0: 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
cab0: 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
cac0: 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
cad0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
cae0: 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  HE option..** Th
caf0: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
cb00: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
cb10: 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
cb20: 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
cb30: 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
cb40: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
cb50: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
cb60: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
cb70: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
cb80: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
cb90: 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
cba0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
cbb0: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
cbc0: 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
cbd0: 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
cbe0: 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
cbf0: 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
cc00: 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
cc10: 20 68 65 61 64 65 72 2e 20 20 54 68 65 20 70 61   header.  The pa
cc20: 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69  ge header size i
cc30: 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73  s 20 to 40 bytes
cc40: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a   depending on.**
cc50: 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74   the host archit
cc60: 65 63 74 75 72 65 2e 20 20 49 74 20 69 73 20 68  ecture.  It is h
cc70: 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
cc80: 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
cc90: 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b  emory,.** to mak
cca0: 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f  e sz a little to
ccb0: 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69  o large.  The fi
ccc0: 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rst.** argument 
ccd0: 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20  should point to 
cce0: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66  an allocation of
ccf0: 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
cd00: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
cd10: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  ** SQLite will u
cd20: 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
cd30: 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
cd40: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
cd50: 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
cd60: 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
cd70: 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
cd80: 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
cd90: 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61 64 64  o cache.  If add
cda0: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
cdb0: 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
cdc0: 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
cdd0: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
cde0: 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74  y this option, t
cdf0: 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f  hen.** SQLite go
ce00: 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
ce10: 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65  alloc()] for the
ce20: 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72   additional stor
ce30: 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68  age space..** Th
ce40: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
ce50: 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20 6f   might use one o
ce60: 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e 20  r more of the N 
ce70: 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 20  buffers to hold 
ce80: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75  .** memory accou
ce90: 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f  nting informatio
cea0: 6e 2e 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69  n. The pointer i
ceb0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
cec0: 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20  ment must.** be 
ced0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
cee0: 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72  byte boundary or
cef0: 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
cf00: 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
cf10: 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  * will be undefi
cf20: 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
cf30: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
cf40: 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
cf50: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
cf60: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
cf70: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
cf80: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
cf90: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
cfa0: 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
cfb0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
cfc0: 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
cfd0: 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
cfe0: 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
cff0: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
d000: 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
d010: 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
d020: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
d030: 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38   arguments: An 8
d040: 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
d050: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
d060: 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
d070: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
d080: 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
d090: 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
d0a0: 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
d0b0: 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72  e..** If the fir
d0c0: 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
d0d0: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
d0e0: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
d0f0: 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
d100: 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
d110: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
d120: 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
d130: 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
d140: 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
d150: 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
d160: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
d170: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
d180: 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a 2a  LLOC].  If the.*
d190: 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
d1a0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
d1b0: 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
d1c0: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
d1d0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
d1e0: 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
d1f0: 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
d200: 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
d210: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
d220: 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
d230: 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
d240: 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
d250: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
d260: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
d270: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
d280: 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
d290: 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
d2a0: 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
d2b0: 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
d2c0: 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
d2d0: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
d2e0: 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
d2f0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
d300: 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
d310: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
d320: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
d330: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
d340: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
d350: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
d360: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
d370: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
d380: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
d390: 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
d3a0: 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
d3b0: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
d3c0: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
d3d0: 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
d3e0: 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
d3f0: 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
d400: 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  QLite.</dd>.**.*
d410: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d420: 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
d430: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
d440: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
d450: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
d460: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
d470: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
d480: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
d490: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
d4a0: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
d4b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
d4c0: 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
d4d0: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
d4e0: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
d4f0: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
d500: 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  tex routines..**
d510: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
d520: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
d530: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
d540: 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
d550: 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
d560: 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
d570: 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
d580: 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
d590: 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
d5a0: 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
d5b0: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64  for example.</dd
d5c0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
d5d0: 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
d5e0: 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
d5f0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
d600: 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
d610: 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
d620: 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65  he default.** me
d630: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
d640: 6c 6f 6f 6b 61 73 69 64 65 20 6f 70 74 69 6d 69  lookaside optimi
d650: 7a 61 74 69 6f 6e 2e 20 20 54 68 65 20 66 69 72  zation.  The fir
d660: 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
d670: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
d680: 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
d690: 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
d6a0: 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
d6b0: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
d6c0: 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
d6d0: 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
d6e0: 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f  nection.  This o
d6f0: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
d700: 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
d710: 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
d720: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42    The [SQLITE_DB
d730: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
d740: 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71  ].** verb to [sq
d750: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
d760: 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
d770: 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
d780: 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
d790: 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
d7a0: 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
d7b0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
d7c0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
d7d0: 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  PCACHE</dt>.** <
d7e0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
d7f0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
d800: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
d810: 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
d820: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
d830: 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
d840: 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
d850: 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69   specifies the i
d860: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61  nterface.** to a
d870: 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
d880: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
d890: 6e 2e 20 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  n.  SQLite makes
d8a0: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
d8b0: 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
d8c0: 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
d8d0: 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
d8e0: 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
d8f0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
d900: 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f  NFIG_GETPCACHE</
d910: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
d920: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
d930: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
d940: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
d950: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
d960: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
d970: 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  ds] object.  SQL
d980: 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
d990: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
d9a0: 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
d9b0: 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
d9c0: 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a   object.</dd>.**
d9d0: 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
d9e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
d9f0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
da00: 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
da10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
da20: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
da30: 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
da40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
da50: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
da60: 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
da70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
da80: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
da90: 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
daa0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
dab0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
dac0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
dad0: 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
dae0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
daf0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
db00: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
db10: 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
db20: 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
db30: 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
db40: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
db50: 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
db60: 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
db70: 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
db80: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
db90: 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
dba0: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
dbb0: 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
dbc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
dbd0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
dbe0: 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
dbf0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
dc00: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
dc10: 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
dc20: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
dc30: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
dc40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
dc50: 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
dc60: 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
dc70: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
dc80: 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
dc90: 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
dca0: 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
dcb0: 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
dcc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
dcd0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
dce0: 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
dcf0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
dd00: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
dd10: 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71         14  /* sq
dd20: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
dd30: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
dd40: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
dd50: 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
dd60: 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
dd70: 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f  e_methods* */../
dd80: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
dd90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
dda0: 69 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c 53  ions {H10170} <S
ddb0: 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  20000>.** EXPERI
ddc0: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
ddd0: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
dde0: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
ddf0: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
de00: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
de10: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
de20: 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
de30: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
de40: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
de50: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
de60: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
de70: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
de80: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
de90: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
dea0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
deb0: 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
dec0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
ded0: 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
dee0: 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
def0: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
df00: 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
df10: 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
df20: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
df30: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
df40: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
df50: 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
df60: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
df70: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
df80: 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
df90: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
dfa0: 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
dfb0: 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
dfc0: 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
dfd0: 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
dfe0: 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
dff0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
e000: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
e010: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  E</dt>.** <dd>Th
e020: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
e030: 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
e040: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
e050: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
e060: 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
e070: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
e080: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
e090: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
e0a0: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
e0b0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
e0c0: 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
e0d0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
e0e0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
e0f0: 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
e100: 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62 75 66  to an memory buf
e110: 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
e120: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
e130: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
e140: 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55  gument may be NU
e150: 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
e160: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
e170: 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
e180: 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
e190: 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
e1a0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
e1b0: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
e1c0: 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
e1d0: 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
e1e0: 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
e1f0: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 61   and the third a
e200: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
e210: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
e220: 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
e230: 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
e240: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
e250: 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
e260: 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
e270: 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
e280: 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
e290: 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
e2a0: 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
e2b0: 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
e2c0: 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
e2d0: 62 6f 75 6e 64 61 72 79 2e 20 20 49 66 20 74 68  boundary.  If th
e2e0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
e2f0: 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  t is not.** a mu
e300: 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
e310: 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 20 72 6f  is internally ro
e320: 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
e330: 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a  e next smaller.*
e340: 2a 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  * multiple of 8.
e350: 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
e360: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
e370: 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  SIDE]</dd>.**.**
e380: 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
e390: 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
e3a0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
e3b0: 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  001  /* void* in
e3c0: 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a  t int */.../*.**
e3d0: 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
e3e0: 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
e3f0: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
e400: 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53 31 30  es {H12200} <S10
e410: 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  700>.**.** The s
e420: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
e430: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
e440: 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
e450: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
e460: 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
e470: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
e480: 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54 68 65  e of SQLite. The
e490: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
e4a0: 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
e4b0: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
e4c0: 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
e4d0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 63   compatibility c
e4e0: 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a  onsiderations..*
e4f0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
e500: 73 3a 0a 2a 2a 20 5b 48 31 32 32 30 31 5d 20 5b  s:.** [H12201] [
e510: 48 31 32 32 30 32 5d 0a 2a 2f 0a 69 6e 74 20 73  H12202].*/.int s
e520: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
e530: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
e540: 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
e550: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
e560: 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
e570: 52 6f 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c  Rowid {H12220} <
e580: 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61  S10700>.**.** Ea
e590: 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53  ch entry in an S
e5a0: 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20  QLite table has 
e5b0: 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
e5c0: 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
e5d0: 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
e5e0: 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
e5f0: 22 5d 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73  "]. The rowid is
e600: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
e610: 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
e620: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
e630: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
e640: 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
e650: 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
e660: 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
e670: 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
e680: 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
e690: 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20  umns. If.** the 
e6a0: 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
e6b0: 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
e6c0: 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
e6d0: 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
e6e0: 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
e6f0: 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
e700: 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  wid..**.** This 
e710: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
e720: 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
e730: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
e740: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
e750: 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64  SERT] into the d
e760: 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
e770: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e780: 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
e790: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
e7a0: 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66    If no successf
e7b0: 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20  ul [INSERT]s.** 
e7c0: 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
e7d0: 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62  ed on that datab
e7e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
e7f0: 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
e800: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 5b 49  ..**.** If an [I
e810: 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
e820: 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
e830: 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  then the [rowid]
e840: 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
e850: 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72  .** row is retur
e860: 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
e870: 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ine as long as t
e880: 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75  he trigger is ru
e890: 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
e8a0: 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74  ce the trigger t
e8b0: 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76  erminates, the v
e8c0: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
e8d0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
e8e0: 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20   reverts to the 
e8f0: 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72  last value inser
e900: 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74  ted before the t
e910: 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a  rigger fired..**
e920: 0a 2a 2a 20 41 6e 20 5b 49 4e 53 45 52 54 5d 20  .** An [INSERT] 
e930: 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
e940: 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
e950: 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
e960: 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
e970: 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
e980: 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
e990: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
e9a0: 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
e9b0: 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54  ne.  Thus INSERT
e9c0: 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
e9d0: 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
e9e0: 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
e9f0: 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
ea00: 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
ea10: 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
ea20: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
ea30: 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
ea40: 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
ea50: 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20  on fails.  When 
ea60: 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
ea70: 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
ea80: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
ea90: 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
eaa0: 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
eab0: 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
eac0: 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
ead0: 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
eae0: 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
eaf0: 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
eb00: 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
eb10: 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
eb20: 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
eb30: 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
eb40: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
eb50: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
eb60: 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
eb70: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
eb80: 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
eb90: 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
eba0: 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
ebb0: 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
ebc0: 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
ebd0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 52 65  d back..**.** Re
ebe0: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
ebf0: 48 31 32 32 32 31 5d 20 5b 48 31 32 32 32 33 5d  H12221] [H12223]
ec00: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
ec10: 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
ec20: 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
ec30: 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
ec40: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
ec50: 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
ec60: 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
ec70: 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
ec80: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
ec90: 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
eca0: 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
ecb0: 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
ecc0: 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
ecd0: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
ece0: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
ecf0: 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
ed00: 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
ed10: 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
ed20: 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
ed30: 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
ed40: 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
ed50: 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
ed60: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
ed70: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
ed80: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
ed90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
eda0: 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
edb0: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b   Rows Modified {
edc0: 48 31 32 32 34 30 7d 20 3c 53 31 30 36 30 30 3e  H12240} <S10600>
edd0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
ede0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
edf0: 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
ee00: 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
ee10: 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
ee20: 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
ee30: 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
ee40: 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
ee50: 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
ee60: 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74  t.** on the [dat
ee70: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ee80: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  ] specified by t
ee90: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
eea0: 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e  er..** Only chan
eeb0: 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
eec0: 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
eed0: 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c  by the [INSERT],
eee0: 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72   [UPDATE],.** or
eef0: 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
ef00: 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
ef10: 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
ef20: 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
ef30: 20 74 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f   triggers are no
ef40: 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74  t counted. Use t
ef50: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
ef60: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
ef70: 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64  ction.** to find
ef80: 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
ef90: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63  r of changes inc
efa0: 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
efb0: 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
efc0: 73 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67 65 73  s..**.** Changes
efd0: 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
efe0: 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79  are simulated by
eff0: 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
f000: 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20  trigger].** are 
f010: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e  not counted.  On
f020: 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68  ly real table ch
f030: 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
f040: 64 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20  d..**.** A "row 
f050: 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61  change" is a cha
f060: 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20  nge to a single 
f070: 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  row of a single 
f080: 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20  table.** caused 
f090: 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45  by an INSERT, DE
f0a0: 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20  LETE, or UPDATE 
f0b0: 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73  statement.  Rows
f0c0: 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61   that.** are cha
f0d0: 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66  nged as side eff
f0e0: 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45  ects of [REPLACE
f0f0: 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
f100: 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
f110: 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
f120: 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41  essing, [DROP TA
f130: 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20  BLE], or by any 
f140: 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69  other.** mechani
f150: 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  sms do not count
f160: 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63   as direct row c
f170: 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  hanges..**.** A 
f180: 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74  "trigger context
f190: 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20  " is a scope of 
f1a0: 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62  execution that b
f1b0: 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64  egins and.** end
f1c0: 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70  s with the scrip
f1d0: 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54  t of a [CREATE T
f1e0: 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
f1f0: 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20  ]. .** Most SQL 
f200: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
f210: 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73  * evaluated outs
f220: 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67  ide of any trigg
f230: 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  er.  This is the
f240: 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20   "top level".** 
f250: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
f260: 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66    If a trigger f
f270: 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f  ires from the to
f280: 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65  p level, a.** ne
f290: 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
f2a0: 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72  t is entered for
f2b0: 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66   the duration of
f2c0: 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69   that one.** tri
f2d0: 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65  gger.  Subtrigge
f2e0: 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e  rs create subcon
f2f0: 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20  texts for their 
f300: 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  duration..**.** 
f310: 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
f320: 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
f330: 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
f340: 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a  ursively does.**
f350: 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65   not create a ne
f360: 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
f370: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  t..**.** This fu
f380: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
f390: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72  he number of dir
f3a0: 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  ect row changes 
f3b0: 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  in the.** most r
f3c0: 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
f3d0: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
f3e0: 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
f3f0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69   the same.** tri
f400: 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
f410: 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 63  .** Thus, when c
f420: 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
f430: 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
f440: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
f450: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
f460: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
f470: 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
f480: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
f490: 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
f4a0: 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
f4b0: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57  he top level.  W
f4c0: 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
f4d0: 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20  f a trigger,.** 
f4e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
f4f0: 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
f500: 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
f510: 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
f520: 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
f530: 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
f540: 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
f550: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
f560: 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
f570: 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
f580: 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
f590: 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77   trigger..** How
f5a0: 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72  ever, the number
f5b0: 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
f5c0: 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
f5d0: 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  es.** caused by 
f5e0: 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63  subtriggers sinc
f5f0: 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65  e those have the
f600: 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a  ir own context..
f610: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
f620: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
f630: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
f640: 65 72 66 61 63 65 20 61 6e 64 20 74 68 65 0a 2a  erface and the.*
f650: 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
f660: 20 70 72 61 67 6d 61 5d 2e 0a 2a 2a 0a 2a 2a 20   pragma]..**.** 
f670: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
f680: 20 5b 48 31 32 32 34 31 5d 20 5b 48 31 32 32 34   [H12241] [H1224
f690: 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  3].**.** If a se
f6a0: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
f6b0: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
f6c0: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
f6d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
f6e0: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
f6f0: 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
f700: 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
f710: 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
f720: 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
f730: 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
f740: 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
f750: 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
f760: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
f770: 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
f780: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
f790: 66 69 65 64 20 7b 48 31 32 32 36 30 7d 20 3c 53  fied {H12260} <S
f7a0: 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  10600>.**.** Thi
f7b0: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
f7c0: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
f7d0: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
f7e0: 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c  sed by [INSERT],
f7f0: 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  .** [UPDATE] or 
f800: 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
f810: 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64  nts since the [d
f820: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f830: 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a  on] was opened..
f840: 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63  ** The count inc
f850: 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65  ludes all change
f860: 73 20 66 72 6f 6d 20 61 6c 6c 20 0a 2a 2a 20 5b  s from all .** [
f870: 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
f880: 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
f890: 74 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ts.  However,.**
f8a0: 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
f8b0: 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
f8c0: 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ges used to impl
f8d0: 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20  ement [REPLACE] 
f8e0: 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20  constraints,.** 
f8f0: 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20  do rollbacks or 
f900: 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
f910: 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45  , or [DROP TABLE
f920: 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54  ] processing.  T
f930: 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73  he.** count does
f940: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77   not include row
f950: 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20  s of views that 
f960: 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44  fire an [INSTEAD
f970: 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a   OF trigger],.**
f980: 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49   though if the I
f990: 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
f9a0: 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  r makes changes 
f9b0: 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73  of its own, thos
f9c0: 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72  e changes .** ar
f9d0: 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 54 68  e counted..** Th
f9e0: 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  e changes are co
f9f0: 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  unted as soon as
fa00: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
fa10: 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
fa20: 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28  s.** completed (
fa30: 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
fa40: 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73  nt handle is pas
fa50: 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
fa60: 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
fa70: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
fa80: 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ()])..**.** See 
fa90: 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
faa0: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
fab0: 65 72 66 61 63 65 20 61 6e 64 20 74 68 65 0a 2a  erface and the.*
fac0: 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
fad0: 20 70 72 61 67 6d 61 5d 2e 0a 2a 2a 0a 2a 2a 20   pragma]..**.** 
fae0: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
faf0: 20 5b 48 31 32 32 36 31 5d 20 5b 48 31 32 32 36   [H12261] [H1226
fb00: 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  3].**.** If a se
fb10: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
fb20: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
fb30: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
fb40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
fb50: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
fb60: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
fb70: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
fb80: 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
fb90: 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
fba0: 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
fbb0: 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
fbc0: 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
fbd0: 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
fbe0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
fbf0: 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
fc00: 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
fc10: 79 20 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 35  y {H12270} <S305
fc20: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  00>.**.** This f
fc30: 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
fc40: 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
fc50: 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
fc60: 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
fc70: 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
fc80: 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
fc90: 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
fca0: 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
fcb0: 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
fcc0: 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
fcd0: 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
fce0: 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
fcf0: 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
fd00: 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
fd10: 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
fd20: 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
fd30: 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
fd40: 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74  .** It is safe t
fd50: 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
fd60: 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
fd70: 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
fd80: 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
fd90: 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
fda0: 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
fdb0: 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
fdc0: 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
fdd0: 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
fde0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
fdf0: 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
fe00: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
fe10: 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
fe20: 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
fe30: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
fe40: 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
fe50: 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f  *.** If an SQL o
fe60: 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
fe70: 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
fe80: 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
fe90: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
fea0: 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
feb0: 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
fec0: 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
fed0: 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
fee0: 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
fef0: 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
ff00: 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
ff10: 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70  .**.** An SQL op
ff20: 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
ff30: 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
ff40: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
ff50: 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49  INTERRUPT]..** I
ff60: 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
ff70: 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
ff80: 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
ff90: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
ffa0: 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
ffb0: 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
ffc0: 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
ffd0: 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
ffe0: 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
fff0: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
10000 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
10010 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
10020 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
10030 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
10040 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
10050 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
10060 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
10070 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10080 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
10090 20 20 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74    Any new SQL st
100a0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
100b0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
100c0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
100d0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
100e0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
100f0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
10100 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
10110 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
10120 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
10130 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
10140 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
10150 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
10160 28 29 20 63 61 6c 6c 2e 20 20 4e 65 77 20 53 51  () call.  New SQ
10170 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
10180 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
10190 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
101a0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
101b0 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
101c0 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
101d0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
101e0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
101f0 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
10200 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
10210 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
10220 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
10230 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
10240 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
10250 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
10260 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
10270 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
10280 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
10290 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
102a0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
102b0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52  returns..**.** R
102c0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
102d0 5b 48 31 32 32 37 31 5d 20 5b 48 31 32 32 37 32  [H12271] [H12272
102e0 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ].**.** If the d
102f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10300 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
10310 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
10320 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
10330 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
10340 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
10350 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
10360 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
10370 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
10380 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
10390 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
103a0 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
103b0 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 7d  omplete {H10510}
103c0 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70200>.**.** 
103d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
103e0 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
103f0 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
10400 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
10410 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
10420 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
10430 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
10440 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
10450 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
10460 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
10470 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
10480 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
10490 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
104a0 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
104b0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
104c0 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
104d0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
104e0 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
104f0 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
10500 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74  atement.  A stat
10510 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
10520 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
10530 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
10540 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
10550 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
10560 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
10570 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
10580 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
10590 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e  ment.  Semicolon
105a0 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
105b0 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
105c0 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
105d0 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
105e0 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
105f0 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
10600 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
10610 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
10620 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
10630 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
10640 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
10650 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
10660 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
10670 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
10680 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
10690 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
106a0 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
106b0 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
106c0 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  gnored..**.** Th
106d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
106e0 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
106f0 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
10700 6c 65 74 65 2e 20 20 49 66 20 61 0a 2a 2a 20 6d  lete.  If a.** m
10710 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10720 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
10730 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
10740 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
10750 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
10760 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
10770 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
10780 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
10790 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
107a0 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
107b0 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65  .**.** If SQLite
107c0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
107d0 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
107e0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
107f0 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
10800 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
10810 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
10820 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
10830 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
10840 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
10850 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
10860 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
10870 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
10880 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
10890 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
108a0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
108b0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
108c0 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
108d0 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
108e0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
108f0 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
10900 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 0a 2a  L is complete..*
10910 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
10920 73 3a 20 5b 48 31 30 35 31 31 5d 20 5b 48 31 30  s: [H10511] [H10
10930 35 31 32 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  512].**.** The i
10940 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
10950 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
10960 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
10970 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
10980 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
10990 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
109a0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
109b0 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
109c0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
109d0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
109e0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
109f0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
10a00 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
10a10 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74   char *sql);.int
10a20 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
10a30 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
10a40 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
10a50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
10a60 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
10a70 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
10a80 20 45 72 72 6f 72 73 20 7b 48 31 32 33 31 30 7d   Errors {H12310}
10a90 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S40400>.**.** 
10aa0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
10ab0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
10ac0 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
10ad0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
10ae0 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
10af0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
10b00 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
10b10 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
10b20 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
10b30 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
10b40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62  ..**.** If the b
10b50 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
10b60 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
10b70 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
10b80 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
10b90 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  D].** is returne
10ba0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
10bb0 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
10bc0 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65  the lock. If the
10bd0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
10be0 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
10bf0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
10c00 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
10c10 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
10c20 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nts..**.** The f
10c30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
10c40 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20   the handler is 
10c50 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
10c60 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
10c70 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
10c80 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
10c90 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
10ca0 65 72 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  er().  The secon
10cb0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
10cc0 20 74 68 65 20 68 61 6e 64 6c 65 72 20 63 61 6c   the handler cal
10cd0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
10ce0 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
10cf0 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
10d00 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
10d10 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
10d20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
10d30 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
10d40 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
10d50 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
10d60 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
10d70 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
10d80 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
10d90 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
10da0 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
10db0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73  OERR_BLOCKED] is
10dc0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66   returned..** If
10dd0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
10de0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
10df0 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
10e00 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
10e10 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
10e20 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
10e30 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
10e40 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
10e50 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
10e60 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
10e70 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
10e80 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
10e90 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
10ea0 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
10eb0 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c  ntention. If SQL
10ec0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
10ed0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
10ee0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
10ef0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
10f00 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
10f10 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
10f20 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
10f30 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
10f40 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
10f50 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
10f60 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
10f70 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
10f80 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
10f90 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
10fa0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
10fb0 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
10fc0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
10fd0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
10fe0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
10ff0 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
11000 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
11010 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
11020 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
11030 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
11040 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
11050 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
11060 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
11070 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
11080 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
11090 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
110a0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
110b0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
110c0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
110d0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
110e0 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
110f0 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
11100 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
11110 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
11120 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
11130 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
11140 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
11150 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
11160 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
11170 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
11180 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
11190 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
111a0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
111b0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
111c0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
111d0 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
111e0 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
111f0 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ceed..**.** The 
11200 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
11210 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
11220 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
11230 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
11240 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
11250 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
11260 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
11270 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
11280 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
11290 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
112a0 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
112b0 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
112c0 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
112d0 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
112e0 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
112f0 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
11300 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
11310 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
11320 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
11330 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
11340 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
11350 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
11360 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
11370 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
11380 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
11390 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
113a0 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
113b0 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62  .  If it is unab
113c0 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
113d0 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
113e0 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
113f0 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
11400 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
11410 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
11420 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
11430 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
11440 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
11450 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
11460 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
11470 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
11480 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
11490 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f  KED].  This erro
114a0 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e  r code promotion
114b0 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75  .** forces an au
114c0 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b  tomatic rollback
114d0 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e   of the changes.
114e0 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20    See the.** <a 
114f0 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77  href="/cvstrac/w
11500 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e  iki?p=Corruption
11510 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
11520 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69  or">.** Corrupti
11530 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
11540 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61  rror</a> wiki pa
11550 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73  ge for a discuss
11560 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68  ion of why.** th
11570 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e  is is important.
11580 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e  .**.** There can
11590 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
115a0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
115b0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
115c0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
115d0 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
115e0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
115f0 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
11600 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
11610 65 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74  et handler.  Not
11620 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
11630 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
11640 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20  eout()].** will 
11650 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61  also set or clea
11660 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  r the busy handl
11670 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
11680 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
11690 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
116a0 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
116b0 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
116c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
116d0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
116e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
116f0 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
11700 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
11710 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
11720 2e 0a 2a 2a 20 0a 2a 2a 20 52 65 71 75 69 72 65  ..** .** Require
11730 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 31  ments:.** [H1231
11740 31 5d 20 5b 48 31 32 33 31 32 5d 20 5b 48 31 32  1] [H12312] [H12
11750 33 31 34 5d 20 5b 48 31 32 33 31 36 5d 20 5b 48  314] [H12316] [H
11760 31 32 33 31 38 5d 0a 2a 2a 0a 2a 2a 20 41 20 62  12318].**.** A b
11770 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
11780 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
11790 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
117a0 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
117b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
117c0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
117d0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
117e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
117f0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
11800 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
11810 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
11820 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
11830 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
11840 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34  t {H12340} <S404
11850 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  10>.**.** This r
11860 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
11870 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
11880 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
11890 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
118a0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
118b0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
118c0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
118d0 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68  s locked.  The h
118e0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
118f0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
11900 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
11910 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
11920 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
11930 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
11940 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41  ated. {H12343} A
11950 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73  fter "ms" millis
11960 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
11970 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
11980 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
11990 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
119a0 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
119b0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
119c0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
119d0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
119e0 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74  .**.** Calling t
119f0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
11a00 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
11a10 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
11a20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
11a30 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
11a40 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ndlers..**.** Th
11a50 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
11a60 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
11a70 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
11a80 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
11a90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11aa0 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f  any any given mo
11ab0 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
11ac0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
11ad0 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
11ae0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
11af0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
11b00 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
11b10 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
11b20 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
11b30 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
11b40 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ared..**.** Requ
11b50 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
11b60 32 33 34 31 5d 20 5b 48 31 32 33 34 33 5d 20 5b  2341] [H12343] [
11b70 48 31 32 33 34 34 5d 0a 2a 2f 0a 69 6e 74 20 73  H12344].*/.int s
11b80 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
11b90 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
11ba0 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
11bb0 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
11bc0 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
11bd0 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
11be0 20 7b 48 31 32 33 37 30 7d 20 3c 53 31 30 30 30   {H12370} <S1000
11bf0 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  0>.**.** Definit
11c00 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
11c10 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
11c20 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
11c30 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
11c40 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
11c50 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
11c60 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
11c70 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
11c80 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
11c90 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
11ca0 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
11cb0 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
11cc0 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
11cd0 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
11ce0 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
11cf0 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
11d00 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
11d10 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
11d20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
11d30 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
11d40 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
11d50 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
11d60 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
11d70 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
11d80 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
11d90 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
11da0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
11db0 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
11dc0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
11dd0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
11de0 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
11df0 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
11e00 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
11e10 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
11e20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
11e30 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
11e40 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
11e50 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
11e60 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
11e70 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
11e80 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
11e90 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
11ea0 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
11eb0 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
11ec0 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
11ed0 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
11ee0 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
11ef0 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
11f00 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
11f10 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
11f20 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
11f30 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
11f40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
11f50 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
11f60 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
11f70 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
11f80 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
11f90 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
11fa0 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
11fb0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
11fc0 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
11fd0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
11fe0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
11ff0 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
12000 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
12010 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
12020 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20  )]..**.** As an 
12030 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
12040 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
12050 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
12060 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
12070 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
12080 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
12090 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
120a0 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
120b0 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
120c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
120d0 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
120e0 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
120f0 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
12100 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
12110 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
12120 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
12130 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
12140 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
12150 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
12160 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
12170 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
12180 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
12190 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
121a0 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
121b0 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
121c0 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
121d0 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
121e0 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
121f0 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
12200 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
12210 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
12220 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
12230 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
12240 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
12250 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
12260 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
12270 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
12280 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
12290 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
122a0 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
122b0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
122c0 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
122d0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
122e0 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
122f0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
12300 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
12310 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
12320 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
12330 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
12340 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
12350 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
12360 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
12370 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
12380 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
12390 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
123a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
123b0 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
123c0 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
123d0 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
123e0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20   parameter.  It 
123f0 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
12400 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
12410 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
12420 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
12430 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
12440 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
12450 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ction has finish
12460 65 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 73  ed using the res
12470 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a  ult, it should.*
12480 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  * pass the point
12490 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74  er to the result
124a0 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65   table to sqlite
124b0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
124c0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
124d0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
124e0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
124f0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
12500 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
12510 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
12520 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
12530 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
12540 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
12550 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
12560 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
12570 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
12580 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
12590 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
125a0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
125b0 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
125c0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
125d0 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
125e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
125f0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
12600 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
12610 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
12620 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
12630 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
12640 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
12650 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
12660 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
12670 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
12680 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
12690 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
126a0 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
126b0 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
126c0 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
126d0 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
126e0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
126f0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
12700 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
12710 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
12720 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
12730 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
12740 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
12750 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
12760 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
12770 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
12780 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
12790 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  errmsg()]..**.**
127a0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
127b0 2a 20 5b 48 31 32 33 37 31 5d 20 5b 48 31 32 33  * [H12371] [H123
127c0 37 33 5d 20 5b 48 31 32 33 37 34 5d 20 5b 48 31  73] [H12374] [H1
127d0 32 33 37 36 5d 20 5b 48 31 32 33 37 39 5d 20 5b  2376] [H12379] [
127e0 48 31 32 33 38 32 5d 0a 2a 2f 0a 69 6e 74 20 73  H12382].*/.int s
127f0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
12800 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
12810 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
12820 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
12830 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
12840 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
12850 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
12860 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
12870 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
12880 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
12890 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
128a0 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
128b0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
128c0 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
128d0 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
128e0 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
128f0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
12900 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
12910 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
12920 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
12930 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
12940 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
12950 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
12960 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
12970 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
12980 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
12990 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
129a0 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  nting Functions 
129b0 7b 48 31 37 34 30 30 7d 20 3c 53 37 30 30 30 30  {H17400} <S70000
129c0 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S20000>.**.** 
129d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
129e0 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
129f0 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
12a00 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
12a10 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
12a20 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
12a30 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ary..**.** The s
12a40 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
12a50 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
12a60 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
12a70 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
12a80 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
12a90 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
12aa0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
12ab0 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
12ac0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
12ad0 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
12ae0 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
12af0 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
12b00 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
12b10 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
12b20 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
12b30 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
12b40 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
12b50 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
12b60 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
12b70 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
12b80 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
12b90 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74  ..**.** In sqlit
12ba0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
12bb0 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
12bc0 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
12bd0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
12be0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
12bf0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
12c00 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
12c10 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
12c20 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
12c30 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
12c40 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
12c50 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
12c60 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
12c70 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
12c80 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
12c90 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
12ca0 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
12cb0 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73  nprintf().  This
12cc0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
12cd0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
12ce0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
12cf0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
12d00 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
12d10 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
12d20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20   Note also that 
12d30 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
12d40 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
12d50 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
12d60 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
12d70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
12d80 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
12d90 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
12da0 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20  to the buffer.  
12db0 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
12dc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
12dd0 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
12de0 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
12df0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
12e00 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
12e10 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
12e20 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12e30 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
12e40 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
12e50 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
12e60 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
12e70 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74  .** As long as t
12e80 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
12e90 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
12ea0 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
12eb0 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
12ec0 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
12ed0 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
12ee0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
12ef0 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70    The first.** p
12f00 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
12f10 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
12f20 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
12f30 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
12f40 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
12f50 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
12f60 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
12f70 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
12f80 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
12f90 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
12fa0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
12fb0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
12fc0 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
12fd0 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
12fe0 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
12ff0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
13000 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
13010 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
13020 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
13030 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
13040 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
13050 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
13060 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
13070 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
13080 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
13090 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ptions..**.** Th
130a0 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
130b0 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
130c0 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
130d0 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74   a null-terminat
130e0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
130f0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
13100 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
13110 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
13120 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
13130 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
13140 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
13150 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
13160 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  l.  By doubling 
13170 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
13180 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
13190 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
131a0 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
131b0 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
131c0 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
131d0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
131e0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
131f0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
13200 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
13210 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
13220 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
13230 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
13240 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
13250 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
13260 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
13270 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
13280 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
13290 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
132a0 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
132b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
132c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
132d0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
132e0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
132f0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
13300 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
13310 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
13320 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
13330 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
13340 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
13350 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
13360 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
13370 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
13380 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
13390 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
133a0 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
133b0 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
133c0 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
133d0 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
133e0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
133f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
13400 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
13410 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
13420 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
13430 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
13440 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
13450 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
13460 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
13470 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
13480 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
13490 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
134a0 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
134b0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
134c0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
134d0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
134e0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
134f0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
13500 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
13510 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
13520 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
13530 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
13540 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
13550 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
13560 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
13570 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
13580 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
13590 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
135a0 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
135b0 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  * The %Q option 
135c0 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
135d0 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
135e0 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
135f0 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
13600 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
13610 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
13620 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
13630 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
13640 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
13650 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
13660 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
13670 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
13680 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
13690 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 20   single quotes) 
136a0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
136b0 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c 20  %Q option.  So, 
136c0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
136d0 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
136e0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
136f0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
13700 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
13710 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
13720 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
13730 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
13740 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
13750 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
13760 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
13770 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
13780 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
13790 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
137a0 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
137b0 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
137c0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
137d0 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
137e0 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
137f0 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
13800 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
13810 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 66  **.** The "%z" f
13820 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
13830 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c   works exactly l
13840 69 6b 65 20 22 25 73 22 20 77 69 74 68 20 74 68  ike "%s" with th
13850 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
13860 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
13870 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
13880 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
13890 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
138a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
138b0 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
138c0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
138d0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 52 65 71   {END}.**.** Req
138e0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
138f0 31 37 34 30 33 5d 20 5b 48 31 37 34 30 36 5d 20  17403] [H17406] 
13900 5b 48 31 37 34 30 37 5d 0a 2a 2f 0a 63 68 61 72  [H17407].*/.char
13910 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
13920 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
13930 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
13940 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
13950 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
13960 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
13970 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
13980 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
13990 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
139a0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
139b0 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
139c0 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53 32 30  em {H17300} <S20
139d0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  000>.**.** The S
139e0 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65 73  QLite core  uses
139f0 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
13a00 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
13a10 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
13a20 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
13a30 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
13a40 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
13a50 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
13a60 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
13a70 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
13a80 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
13a90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
13aa0 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
13ab0 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
13ac0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
13ad0 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
13ae0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  rations..**.** T
13af0 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
13b00 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
13b10 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
13b20 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
13b30 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
13b40 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
13b50 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
13b60 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49   parameter..** I
13b70 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
13b80 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
13b90 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
13ba0 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
13bb0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
13bc0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
13bd0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
13be0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
13bf0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
13c00 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
13c10 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
13c20 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
13c30 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
13c40 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  ** Calling sqlit
13c50 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
13c60 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
13c70 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
13c80 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
13c90 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
13ca0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
13cb0 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
13cc0 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
13cd0 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 54 68  t be reused.  Th
13ce0 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
13cf0 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
13d00 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
13d10 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
13d20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
13d30 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
13d40 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
13d50 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
13d60 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
13d70 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
13d80 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
13d90 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
13da0 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
13db0 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
13dc0 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
13dd0 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
13de0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
13df0 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
13e00 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
13e10 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
13e20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
13e30 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
13e40 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
13e50 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
13e60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
13e70 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
13e80 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
13e90 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
13ea0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
13eb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
13ec0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
13ed0 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  c()..**.** The s
13ee0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
13ef0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
13f00 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
13f10 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
13f20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
13f30 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
13f40 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
13f50 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
13f60 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f  meter.  The memo
13f70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
13f80 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74   be resized is t
13f90 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
13fa0 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65 20 66  meter.  If the f
13fb0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
13fc0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
13fd0 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
13fe0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
13ff0 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
14000 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
14010 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
14020 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
14030 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
14040 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
14050 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
14060 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70   If the second p
14070 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
14080 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
14090 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
140a0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
140b0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
140c0 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
140d0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
140e0 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
140f0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
14100 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
14110 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
14120 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14130 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
14140 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
14150 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
14160 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
14170 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
14180 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
14190 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
141a0 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20  ilable..** If M 
141b0 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
141c0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
141d0 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
141e0 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
141f0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
14200 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
14210 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
14220 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
14230 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
14240 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
14250 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
14260 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
14270 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65  ** If sqlite3_re
14280 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
14290 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
142a0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
142b0 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
142c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72  .**.** The memor
142d0 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  y returned by sq
142e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61  lite3_malloc() a
142f0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
14300 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  oc().** is alway
14310 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
14320 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
14330 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a  boundary. {END}.
14340 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  **.** The defaul
14350 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
14360 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61   of the memory a
14370 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
14380 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68 65 20  tem uses.** the 
14390 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
143a0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 70  c() and free() p
143b0 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 73  rovided by the s
143c0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
143d0 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48  y..** {H17382} H
143e0 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
143f0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14400 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
14410 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e  _MEMORY_SIZE=<i>
14420 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f  NNN</i> C prepro
14430 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 28 77 68  cessor macro (wh
14440 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a  ere <i>NNN</i>.*
14450 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29  * is an integer)
14460 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72  , then SQLite cr
14470 65 61 74 65 20 61 20 73 74 61 74 69 63 20 61 72  eate a static ar
14480 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74 0a  ray of at least.
14490 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79  ** <i>NNN</i> by
144a0 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20  tes in size and 
144b0 75 73 65 73 20 74 68 61 74 20 61 72 72 61 79 20  uses that array 
144c0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
144d0 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79  ynamic.** memory
144e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
144f0 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69  s. {END}  Additi
14500 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  onal memory allo
14510 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a  cator options.**
14520 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
14530 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
14540 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
14550 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
14560 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
14570 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
14580 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
14590 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
145a0 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
145b0 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
145c0 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
145d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
145e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
145f0 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
14600 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
14610 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
14620 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
14630 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
14640 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
14650 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57  sed..**.** The W
14660 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
14670 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a  ace layer calls.
14680 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
14690 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
146a0 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
146b0 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
146c0 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
146d0 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
146e0 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
146f0 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
14700 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
14710 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
14720 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
14730 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
14740 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
14750 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
14760 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62   are detected, b
14770 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72  ut.** they are r
14780 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
14790 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
147a0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
147b0 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
147c0 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
147d0 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
147e0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 30  ments:.** [H1730
147f0 33 5d 20 5b 48 31 37 33 30 34 5d 20 5b 48 31 37  3] [H17304] [H17
14800 33 30 35 5d 20 5b 48 31 37 33 30 36 5d 20 5b 48  305] [H17306] [H
14810 31 37 33 31 30 5d 20 5b 48 31 37 33 31 32 5d 20  17310] [H17312] 
14820 5b 48 31 37 33 31 35 5d 20 5b 48 31 37 33 31 38  [H17315] [H17318
14830 5d 0a 2a 2a 20 5b 48 31 37 33 32 31 5d 20 5b 48  ].** [H17321] [H
14840 31 37 33 32 32 5d 20 5b 48 31 37 33 32 33 5d 0a  17322] [H17323].
14850 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
14860 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
14870 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
14880 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
14890 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
148a0 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
148b0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
148c0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
148d0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
148e0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
148f0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
14900 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
14910 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
14920 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
14930 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
14940 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
14950 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
14960 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
14970 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
14980 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
14990 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
149a0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
149b0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
149c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
149d0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
149e0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
149f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
14a00 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
14a10 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
14a20 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
14a30 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
14a40 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
14a50 74 69 73 74 69 63 73 20 7b 48 31 37 33 37 30 7d  tistics {H17370}
14a60 20 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S30210>.**.** 
14a70 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
14a80 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
14a90 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
14aa0 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
14ab0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
14ac0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
14ad0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
14ae0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
14af0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
14b00 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
14b10 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
14b20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14b30 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
14b40 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
14b50 2a 20 5b 48 31 37 33 37 31 5d 20 5b 48 31 37 33  * [H17371] [H173
14b60 37 33 5d 20 5b 48 31 37 33 37 34 5d 20 5b 48 31  73] [H17374] [H1
14b70 37 33 37 35 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33  7375].*/.sqlite3
14b80 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
14b90 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
14ba0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
14bb0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
14bc0 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
14bd0 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
14be0 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
14bf0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
14c00 65 6e 65 72 61 74 6f 72 20 7b 48 31 37 33 39 30  enerator {H17390
14c10 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20000>.**.**
14c20 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
14c30 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
14c40 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
14c50 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
14c60 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
14c70 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
14c80 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
14c90 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
14ca0 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
14cb0 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
14cc0 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
14cd0 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
14ce0 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
14cf0 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
14d00 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
14d10 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
14d20 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
14d30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
14d40 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
14d50 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
14d60 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
14d70 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
14d80 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
14d90 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
14da0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
14db0 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
14dc0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
14dd0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a   buffer P..**.**
14de0 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
14df0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
14e00 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20  invoked (either 
14e10 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79  internally or by
14e20 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
14e30 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73  ion) the PRNG is
14e40 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
14e50 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
14e60 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52  d.** from the xR
14e70 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
14e80 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
14e90 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
14ea0 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20  ject..** On all 
14eb0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
14ec0 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75  ations, the pseu
14ed0 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
14ee0 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
14ef0 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
14f00 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
14f10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
14f20 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
14f30 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20  * method..**.** 
14f40 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
14f50 20 5b 48 31 37 33 39 32 5d 0a 2a 2f 0a 76 6f 69   [H17392].*/.voi
14f60 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
14f70 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
14f80 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
14f90 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
14fa0 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
14fb0 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32  n Callbacks {H12
14fc0 35 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a  500} <S70100>.**
14fd0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
14fe0 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74   registers a aut
14ff0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
15000 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
15010 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
15020 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
15030 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
15040 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
15050 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
15060 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
15070 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
15080 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
15090 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
150a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
150b0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
150c0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
150d0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
150e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
150f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
15100 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
15110 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20    At various.** 
15120 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
15130 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
15140 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
15150 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
15160 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
15170 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
15180 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
15190 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
151a0 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
151b0 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
151c0 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20  e allowed.  The 
151d0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
151e0 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
151f0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
15200 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
15210 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
15220 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
15230 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
15240 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
15250 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
15260 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
15270 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
15280 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
15290 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
152a0 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
152b0 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
152c0 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
152d0 20 65 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20   error.  If the 
152e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
152f0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
15300 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
15310 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
15320 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
15330 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
15340 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
15350 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
15360 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
15370 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
15380 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
15390 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
153a0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
153b0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
153c0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
153d0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
153e0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
153f0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
15400 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
15410 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63   ok.  When the c
15420 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
15430 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
15440 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
15450 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
15460 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
15470 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
15480 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
15490 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
154a0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
154b0 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
154c0 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
154d0 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65  nied. .**.** The
154e0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
154f0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
15500 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
15510 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
15520 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
15530 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
15540 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
15550 69 6e 74 65 72 66 61 63 65 2e 20 54 68 65 20 73  interface. The s
15560 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
15570 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
15580 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
15590 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
155a0 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
155b0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
155c0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
155d0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
155e0 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72 64  rized. The third
155f0 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
15600 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
15610 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
15620 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
15630 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
15640 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
15650 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
15660 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
15670 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
15680 2a 0a 2a 2a 20 49 66 20 74 68 65 20 61 63 74 69  *.** If the acti
15690 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
156a0 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
156b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
156c0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
156d0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
156e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
156f0 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
15700 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
15710 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
15720 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
15730 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
15740 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
15750 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
15760 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
15770 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
15780 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
15790 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
157a0 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
157b0 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
157c0 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
157d0 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
157e0 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
157f0 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 49 66 20   a table..** If 
15800 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
15810 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
15820 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
15830 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
15840 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
15850 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
15860 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
15870 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
15880 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
15890 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
158a0 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
158b0 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
158c0 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
158d0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
158e0 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
158f0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
15900 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
15910 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
15920 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
15930 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
15940 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
15950 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
15960 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
15970 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
15980 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
15990 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
159a0 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
159b0 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
159c0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
159d0 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
159e0 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
159f0 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
15a00 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
15a10 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
15a20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
15a30 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
15a40 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
15a50 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
15a60 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
15a70 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
15a80 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
15a90 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
15aa0 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
15ab0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
15ac0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
15ad0 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
15ae0 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
15af0 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
15b00 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
15b10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
15b20 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
15b30 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
15b40 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
15b50 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
15b60 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
15b70 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
15b80 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
15b90 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
15ba0 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
15bb0 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
15bc0 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
15bd0 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
15be0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
15bf0 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
15c00 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
15c10 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
15c20 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
15c30 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
15c40 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
15c50 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
15c60 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
15c70 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
15c80 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
15c90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15ca0 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
15cb0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
15cc0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
15cd0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
15ce0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
15cf0 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68  all.  Disable th
15d00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
15d10 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
15d20 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
15d30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
15d40 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
15d50 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
15d60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
15d70 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
15d80 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
15d90 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
15da0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15db0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
15dc0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
15dd0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
15de0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
15df0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
15e00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
15e10 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
15e20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
15e30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
15e40 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
15e50 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
15e60 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
15e70 2a 2a 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** When [sqlite3
15e80 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
15e90 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
15ea0 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
15eb0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
15ec0 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
15ed0 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
15ee0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
15ef0 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
15f00 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
15f10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
15f20 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
15f30 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
15f40 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
15f50 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
15f60 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
15f70 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
15f80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ()]..**.** Note 
15f90 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
15fa0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
15fb0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
15fc0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
15fd0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
15fe0 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
15ff0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
16000 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
16010 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
16020 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
16030 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
16040 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
16050 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
16060 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
16070 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
16080 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
16090 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
160a0 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
160b0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
160c0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2a  chema change..**
160d0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
160e0 3a 0a 2a 2a 20 5b 48 31 32 35 30 31 5d 20 5b 48  :.** [H12501] [H
160f0 31 32 35 30 32 5d 20 5b 48 31 32 35 30 33 5d 20  12502] [H12503] 
16100 5b 48 31 32 35 30 34 5d 20 5b 48 31 32 35 30 35  [H12504] [H12505
16110 5d 20 5b 48 31 32 35 30 36 5d 20 5b 48 31 32 35  ] [H12506] [H125
16120 30 37 5d 20 5b 48 31 32 35 31 30 5d 0a 2a 2a 20  07] [H12510].** 
16130 5b 48 31 32 35 31 31 5d 20 5b 48 31 32 35 31 32  [H12511] [H12512
16140 5d 20 5b 48 31 32 35 32 30 5d 20 5b 48 31 32 35  ] [H12520] [H125
16150 32 31 5d 20 5b 48 31 32 35 32 32 5d 0a 2a 2f 0a  21] [H12522].*/.
16160 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
16170 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
16180 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
16190 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
161a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
161b0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
161c0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
161d0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
161e0 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
161f0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
16200 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
16210 20 7b 48 31 32 35 39 30 7d 20 3c 48 31 32 35 30   {H12590} <H1250
16220 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0>.**.** The [sq
16230 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
16240 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
16250 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
16260 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
16270 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
16280 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
16290 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
162a0 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
162b0 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
162c0 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
162d0 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
162e0 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
162f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
16300 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
16310 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
16320 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
16330 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
16340 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66  rmation..*/.#def
16350 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
16360 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
16370 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
16380 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
16390 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
163a0 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
163b0 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
163c0 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
163d0 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
163e0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
163f0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
16400 74 69 6f 6e 20 43 6f 64 65 73 20 7b 48 31 32 35  tion Codes {H125
16410 35 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a  50} <H12500>.**.
16420 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
16430 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
16440 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
16450 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
16460 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
16470 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
16480 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
16490 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
164a0 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
164b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
164c0 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
164d0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
164e0 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
164f0 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
16500 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
16510 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
16520 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
16530 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
16540 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
16550 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
16560 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
16570 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
16580 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
16590 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
165a0 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
165b0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
165c0 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
165d0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
165e0 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
165f0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
16600 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
16610 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
16620 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
16630 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
16640 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
16650 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
16660 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74 68  ameter.  The 5th
16670 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
16680 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
16690 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
166a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
166b0 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
166c0 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
166d0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54  f applicable.  T
166e0 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
166f0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
16700 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
16710 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
16720 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
16730 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
16740 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
16750 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
16760 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
16770 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
16780 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
16790 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f  ectly from.** to
167a0 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
167b0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
167c0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 35 35 31  ents:.** [H12551
167d0 5d 20 5b 48 31 32 35 35 32 5d 20 5b 48 31 32 35  ] [H12552] [H125
167e0 35 33 5d 20 5b 48 31 32 35 35 34 5d 0a 2a 2f 0a  53] [H12554].*/.
167f0 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
16800 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16810 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
16820 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
16830 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
16840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
16850 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
16860 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
16870 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
16880 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
16890 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
168a0 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
168b0 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
168c0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
168d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
168e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
168f0 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
16900 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
16910 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
16920 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
16930 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
16940 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
16950 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
16960 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
16970 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
16980 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
16990 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
169a0 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
169b0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
169c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
169d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
169e0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
169f0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
16a00 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
16a10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
16a20 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
16a30 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
16a40 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
16a50 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
16a60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
16a70 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
16a80 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
16a90 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
16aa0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
16ab0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16ac0 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
16ad0 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
16ae0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
16af0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
16b00 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16b10 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
16b20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
16b30 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
16b40 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
16b50 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
16b60 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
16b70 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
16b80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
16b90 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
16ba0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16bb0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
16bc0 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
16bd0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
16be0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
16bf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16c00 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
16c10 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
16c20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
16c30 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
16c40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16c50 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
16c60 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
16c70 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
16c80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
16c90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16ca0 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
16cb0 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
16cc0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
16cd0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
16ce0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
16cf0 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
16d00 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
16d10 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
16d20 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
16d30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
16d40 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
16d50 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
16d60 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
16d70 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
16d80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
16d90 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
16da0 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
16db0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
16dc0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
16dd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
16de0 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
16df0 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
16e00 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
16e10 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
16e20 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
16e30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
16e40 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
16e50 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
16e60 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
16e70 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
16e80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
16e90 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
16ea0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
16eb0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
16ec0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
16ed0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
16ee0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
16ef0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
16f00 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
16f10 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
16f20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
16f30 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
16f40 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
16f50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
16f60 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
16f70 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
16f80 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
16f90 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
16fa0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16fb0 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
16fc0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
16fd0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
16fe0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
16ff0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17000 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
17010 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
17020 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
17030 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
17040 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17050 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
17060 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
17070 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
17080 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
17090 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
170a0 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
170b0 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
170c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
170d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
170e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
170f0 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
17100 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
17110 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
17120 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
17130 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17140 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
17150 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
17160 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
17170 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
17180 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17190 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
171a0 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
171b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
171c0 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
171d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
171e0 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
171f0 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
17200 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
17210 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
17220 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17230 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
17240 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
17250 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
17260 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
17270 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
17280 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48  ing Functions {H
17290 31 32 32 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a  12280} <S60400>.
172a0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
172b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
172c0 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
172d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
172e0 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
172f0 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
17300 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
17310 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
17320 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
17330 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
17340 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
17350 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
17360 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
17370 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
17380 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
17390 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
173a0 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
173b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
173c0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
173d0 20 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38   returns a UTF-8
173e0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
173f0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
17400 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73  text.** as the s
17410 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
17420 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
17430 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c    Additional cal
17440 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20  lbacks occur.** 
17450 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
17460 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
17470 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
17480 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
17490 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
174a0 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
174b0 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
174c0 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
174d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
174e0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
174f0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
17500 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
17510 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
17520 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
17530 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20   finishes.  The 
17540 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
17550 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
17560 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
17570 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
17580 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
17590 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
175a0 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
175b0 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
175c0 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  o run..**.** Req
175d0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
175e0 31 32 32 38 31 5d 20 5b 48 31 32 32 38 32 5d 20  12281] [H12282] 
175f0 5b 48 31 32 32 38 33 5d 20 5b 48 31 32 32 38 34  [H12283] [H12284
17600 5d 20 5b 48 31 32 32 38 35 5d 20 5b 48 31 32 32  ] [H12285] [H122
17610 38 37 5d 20 5b 48 31 32 32 38 38 5d 20 5b 48 31  87] [H12288] [H1
17620 32 32 38 39 5d 0a 2a 2a 20 5b 48 31 32 32 39 30  2289].** [H12290
17630 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45  ].*/.SQLITE_EXPE
17640 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
17650 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
17660 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
17670 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
17680 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
17690 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
176a0 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
176b0 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
176c0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
176d0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
176e0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
176f0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
17700 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17710 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
17720 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31  ss Callbacks {H1
17730 32 39 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2910} <S60400>.*
17740 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
17750 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63  e configures a c
17760 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
17770 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65   - the.** progre
17780 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68  ss callback - th
17790 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65  at is invoked pe
177a0 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
177b0 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e  g long.** runnin
177c0 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  g calls to [sqli
177d0 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
177e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
177f0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  d.** [sqlite3_ge
17800 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20  t_table()].  An 
17810 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
17820 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
17830 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
17840 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
17850 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
17860 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72  .**.** If the pr
17870 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
17880 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
17890 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
178a0 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
178b0 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
178c0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
178d0 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
178e0 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
178f0 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
17900 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
17910 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
17920 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
17930 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
17940 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
17950 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
17960 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
17970 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
17980 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
17990 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
179a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
179b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
179c0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
179d0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
179e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
179f0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
17a00 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
17a10 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
17a20 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
17a30 3a 0a 2a 2a 20 5b 48 31 32 39 31 31 5d 20 5b 48  :.** [H12911] [H
17a40 31 32 39 31 32 5d 20 5b 48 31 32 39 31 33 5d 20  12912] [H12913] 
17a50 5b 48 31 32 39 31 34 5d 20 5b 48 31 32 39 31 35  [H12914] [H12915
17a60 5d 20 5b 48 31 32 39 31 36 5d 20 5b 48 31 32 39  ] [H12916] [H129
17a70 31 37 5d 20 5b 48 31 32 39 31 38 5d 0a 2a 2a 0a  17] [H12918].**.
17a80 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
17a90 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
17aa0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
17ab0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
17ac0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
17ad0 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
17ae0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
17af0 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37 30  onnection {H1270
17b00 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a  0} <S40200>.**.*
17b10 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
17b20 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
17b30 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68  database file wh
17b40 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65  ose name is give
17b50 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65  n by the.** file
17b60 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54  name argument. T
17b70 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
17b80 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
17b90 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
17ba0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
17bb0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
17bc0 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
17bd0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
17be0 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
17bf0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
17c00 70 65 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61  pen16(). A [data
17c10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17c20 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
17c30 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
17c40 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
17c50 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
17c60 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
17c70 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
17c80 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
17c90 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
17ca0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
17cb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
17cc0 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
17cd0 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
17ce0 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
17cf0 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
17d00 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
17d10 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74  .** object. If t
17d20 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
17d30 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
17d40 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
17d50 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
17d60 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
17d70 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
17d80 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
17d90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
17da0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
17db0 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
17dc0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
17dd0 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
17de0 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
17df0 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
17e00 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
17e10 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e  on of the error.
17e20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  .**.** The defau
17e30 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
17e40 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
17e50 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
17e60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
17e70 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
17e80 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
17e90 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
17ea0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
17eb0 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
17ec0 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
17ed0 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
17ee0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
17ef0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
17f00 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
17f10 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
17f20 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
17f30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17f40 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
17f50 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
17f60 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
17f70 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
17f80 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
17f90 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
17fa0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
17fb0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
17fc0 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
17fd0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
17fe0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
17ff0 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
18000 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
18010 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
18020 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
18030 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
18040 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
18050 20 20 54 68 65 20 66 6c 61 67 73 20 70 61 72 61    The flags para
18060 6d 65 74 65 72 20 63 61 6e 20 74 61 6b 65 20 6f  meter can take o
18070 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
18080 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
18090 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
180a0 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
180b0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
180c0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
180d0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
180e0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
180f0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
18100 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  .** and/or [SQLI
18110 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
18120 41 43 48 45 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a  ACHE] flags:.**.
18130 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b  ** <dl>.** <dt>[
18140 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
18150 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
18160 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
18170 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
18180 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
18190 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
181a0 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
181b0 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
181c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
181d0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51  d>.**.** <dt>[SQ
181e0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
181f0 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
18200 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
18210 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
18220 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
18230 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
18240 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
18250 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
18260 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
18270 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
18280 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
18290 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
182a0 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
182b0 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
182c0 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
182d0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
182e0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49  .**.** <dt>[SQLI
182f0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
18300 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
18310 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
18320 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
18330 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
18340 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
18350 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
18360 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74  ates it if.** it
18370 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
18380 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
18390 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
183a0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
183b0 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
183c0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
183d0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
183e0 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  d>.** </dl>.**.*
183f0 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
18400 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
18410 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
18420 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
18430 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
18440 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65  own above or one
18450 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74   of the combinat
18460 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
18470 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74   combined.** wit
18480 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
18490 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
184a0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
184b0 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  TEX],.** [SQLITE
184c0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
184d0 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  E] and/or [SQLIT
184e0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
184f0 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68  HE] flags,.** th
18500 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
18510 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
18520 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c 49  .** If the [SQLI
18530 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
18540 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
18550 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
18560 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
18570 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
18580 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
18590 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
185a0 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
185b0 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
185c0 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
185d0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
185e0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 49  r start-time.  I
185f0 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
18600 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
18610 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
18620 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
18630 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
18640 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
18650 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
18660 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
18670 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
18680 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
18690 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
186a0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
186b0 69 6d 65 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ime..** The [SQL
186c0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
186d0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
186e0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
186f0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
18700 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
18710 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
18720 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
18730 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
18740 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
18750 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
18760 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
18770 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
18780 68 65 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b  he()].  The.** [
18790 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
187a0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
187b0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
187c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
187d0 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
187e0 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
187f0 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
18800 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
18810 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
18820 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
18830 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
18840 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
18850 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
18860 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
18870 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
18880 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d  tion.  This in-m
18890 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
188a0 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
188b0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
188c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
188d0 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
188e0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
188f0 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
18900 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
18910 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
18920 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
18930 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
18940 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
18950 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
18960 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
18970 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
18980 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
18990 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
189a0 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
189b0 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
189c0 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
189d0 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
189e0 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
189f0 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66  iguity..**.** If
18a00 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
18a10 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
18a20 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
18a30 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
18a40 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
18a50 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
18a60 20 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64    This private d
18a70 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
18a80 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
18a90 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
18aa0 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
18ab0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
18ac0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
18ad0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
18ae0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
18af0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
18b00 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
18b10 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
18b20 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
18b30 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
18b40 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
18b50 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
18b60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18b70 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49  n should use.  I
18b80 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
18b90 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
18ba0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
18bb0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
18bc0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
18bd0 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
18be0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
18bf0 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
18c00 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
18c10 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
18c20 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
18c30 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
18c40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
18c50 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
18c60 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
18c70 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
18c80 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
18c90 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
18ca0 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
18cb0 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
18cc0 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
18cd0 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
18ce0 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
18cf0 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
18d00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
18d10 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
18d20 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  2()..**.** Requi
18d30 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
18d40 37 30 31 5d 20 5b 48 31 32 37 30 32 5d 20 5b 48  701] [H12702] [H
18d50 31 32 37 30 33 5d 20 5b 48 31 32 37 30 34 5d 20  12703] [H12704] 
18d60 5b 48 31 32 37 30 36 5d 20 5b 48 31 32 37 30 37  [H12706] [H12707
18d70 5d 20 5b 48 31 32 37 30 39 5d 20 5b 48 31 32 37  ] [H12709] [H127
18d80 31 31 5d 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 20  11].** [H12712] 
18d90 5b 48 31 32 37 31 33 5d 20 5b 48 31 32 37 31 34  [H12713] [H12714
18da0 5d 20 5b 48 31 32 37 31 37 5d 20 5b 48 31 32 37  ] [H12717] [H127
18db0 31 39 5d 20 5b 48 31 32 37 32 31 5d 20 5b 48 31  19] [H12721] [H1
18dc0 32 37 32 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2723].*/.int sql
18dd0 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
18de0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
18df0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
18e00 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
18e10 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
18e20 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
18e30 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
18e40 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
18e50 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
18e60 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
18e70 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
18e80 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
18e90 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
18ea0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
18eb0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
18ec0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
18ed0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
18ee0 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
18ef0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
18f00 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
18f10 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
18f20 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
18f30 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
18f40 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
18f50 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
18f60 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
18f70 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
18f80 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
18f90 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
18fa0 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
18fb0 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
18fc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
18fd0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
18fe0 65 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d  essages {H12800}
18ff0 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60200>.**.** 
19000 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
19010 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
19020 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
19030 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
19040 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
19050 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
19060 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
19070 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
19080 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
19090 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
190a0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
190b0 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
190c0 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
190d0 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
190e0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
190f0 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
19100 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
19110 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
19120 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
19130 65 66 69 6e 65 64 2e 20 20 54 68 65 20 73 71 6c  efined.  The sql
19140 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
19150 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72  rcode().** inter
19160 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65  face is the same
19170 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
19180 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
19190 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  he .** [extended
191a0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76   result code] ev
191b0 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64  en when extended
191c0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
191d0 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a  e.** disabled..*
191e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
191f0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
19200 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
19210 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
19220 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
19230 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
19240 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
19250 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
19260 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
19270 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20  y..** Memory to 
19280 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
19290 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
192a0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
192b0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
192c0 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
192d0 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
192e0 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
192f0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
19300 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
19310 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
19320 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
19330 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
19340 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
19350 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
19360 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
19370 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ions..**.** When
19380 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
19390 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
193a0 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
193b0 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
193c0 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
193d0 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
193e0 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
193f0 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
19400 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
19410 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
19420 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
19430 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
19440 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
19450 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
19460 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
19470 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
19480 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
19490 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
194a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
194b0 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
194c0 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
194d0 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
194e0 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
194f0 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
19500 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
19510 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
19520 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
19530 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
19540 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
19550 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
19560 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
19570 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
19580 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
19590 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
195a0 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
195b0 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
195c0 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
195d0 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
195e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
195f0 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
19600 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
19610 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
19620 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
19630 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
19640 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
19650 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
19660 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
19670 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
19680 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
19690 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a  y not be set..**
196a0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
196b0 3a 0a 2a 2a 20 5b 48 31 32 38 30 31 5d 20 5b 48  :.** [H12801] [H
196c0 31 32 38 30 32 5d 20 5b 48 31 32 38 30 33 5d 20  12802] [H12803] 
196d0 5b 48 31 32 38 30 37 5d 20 5b 48 31 32 38 30 38  [H12807] [H12808
196e0 5d 20 5b 48 31 32 38 30 39 5d 0a 2a 2f 0a 69 6e  ] [H12809].*/.in
196f0 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
19700 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
19710 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
19720 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
19730 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
19740 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
19750 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
19760 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
19770 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
19780 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
19790 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
197a0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
197b0 48 31 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e  H13000} <H13010>
197c0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
197d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
197e0 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
197f0 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
19800 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
19810 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
19820 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
19830 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  L statement..** 
19840 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76  This object is v
19850 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61  ariously known a
19860 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74  s a "prepared st
19870 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a  atement" or a.**
19880 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73   "compiled SQL s
19890 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d  tatement" or sim
198a0 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d  ply as a "statem
198b0 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent"..**.** The 
198c0 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
198d0 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
198e0 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
198f0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
19900 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
19910 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
19920 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19930 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
19940 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
19950 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
19960 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f  nd values to [ho
19970 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75  st parameters] u
19980 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
19990 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
199a0 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
199b0 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
199c0 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
199d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
199e0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
199f0 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
19a00 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  he statement usi
19a10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
19a20 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
19a30 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
19a40 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
19a50 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
19a60 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
19a70 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
19a80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
19a90 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
19aa0 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f  >.**.** Refer to
19ab0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f   documentation o
19ac0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74  n individual met
19ad0 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61  hods above for a
19ae0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
19af0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  ormation..*/.typ
19b00 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
19b10 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
19b20 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
19b30 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
19b40 20 4c 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d   Limits {H12760}
19b50 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20600>.**.** 
19b60 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
19b70 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
19b80 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
19b90 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
19ba0 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
19bb0 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
19bc0 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
19bd0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
19be0 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
19bf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
19c00 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
19c10 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
19c20 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
19c30 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
19c40 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
19c50 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
19c60 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
19c70 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
19c80 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
19c90 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
19ca0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
19cb0 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
19cc0 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
19cd0 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69  uct.  The functi
19ce0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f  on returns the o
19cf0 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20  ld limit..**.** 
19d00 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
19d10 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
19d20 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
19d30 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
19d40 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20  * For the limit 
19d50 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49  category of SQLI
19d60 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65  TE_LIMIT_XYZ the
19d70 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
19d80 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
19d90 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62   bound].** set b
19da0 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  y a compile-time
19db0 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
19dc0 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20  macro named .** 
19dd0 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
19de0 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54  _MAX_XYZ]..** (T
19df0 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
19e00 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
19e10 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
19e20 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20  .** Attempts to 
19e30 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
19e40 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
19e50 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
19e60 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
19e70 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
19e80 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a  d upper limit..*
19e90 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69  *.** Run time li
19ea0 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
19eb0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
19ec0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
19ed0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
19ee0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
19ef0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
19f00 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
19f10 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
19f20 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
19f30 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
19f40 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
19f50 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
19f60 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
19f70 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
19f80 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
19f90 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
19fa0 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
19fb0 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
19fc0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
19fd0 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
19fe0 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
19ff0 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
1a000 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
1a010 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
1a020 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
1a030 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
1a040 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
1a050 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
1a060 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
1a070 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
1a080 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
1a090 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
1a0a0 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
1a0b0 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
1a0c0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
1a0d0 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
1a0e0 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
1a0f0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1a100 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
1a110 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
1a120 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
1a130 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
1a140 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
1a150 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
1a160 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
1a170 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
1a180 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
1a190 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
1a1a0 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
1a1b0 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
1a1c0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
1a1d0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
1a1e0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
1a1f0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1a200 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 36 32 5d 20  ts:.** [H12762] 
1a210 5b 48 31 32 37 36 36 5d 20 5b 48 31 32 37 36 39  [H12766] [H12769
1a220 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1a230 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
1a240 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
1a250 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
1a260 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
1a270 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
1a280 20 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36   {H12790} <H1276
1a290 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
1a2a0 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
1a2b0 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   {limit categori
1a2c0 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
1a2d0 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
1a2e0 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
1a2f0 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
1a300 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
1a310 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
1a320 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
1a330 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
1a340 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
1a350 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
1a360 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
1a370 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
1a380 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
1a390 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
1a3a0 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
1a3b0 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
1a3c0 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
1a3d0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1a3e0 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
1a3f0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1a400 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
1a410 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
1a420 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a   table row.<dd>.
1a430 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1a440 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
1a450 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1a460 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
1a470 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
1a480 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ment.</dd>.**.**
1a490 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1a4a0 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
1a4b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1a4c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1a4d0 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
1a4e0 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
1a4f0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
1a500 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
1a510 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
1a520 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1a530 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
1a540 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
1a550 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
1a560 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  use.</dd>.**.** 
1a570 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1a580 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
1a590 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1a5a0 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
1a5b0 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
1a5c0 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
1a5d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1a5e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
1a5f0 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
1a600 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1a610 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
1a620 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
1a630 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1a640 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
1a650 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
1a660 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
1a670 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1a680 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
1a690 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
1a6a0 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
1a6b0 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
1a6c0 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
1a6d0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
1a6e0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1a6f0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
1a700 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
1a710 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1a720 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
1a730 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
1a740 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1a750 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
1a760 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
1a770 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1a780 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
1a790 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
1a7a0 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  s].</dd>.**.** <
1a7b0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1a7c0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
1a7d0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1a7e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
1a7f0 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
1a800 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
1a810 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
1a820 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
1a830 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1a840 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1a850 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
1a860 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1a870 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76  imum number of v
1a880 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53  ariables in an S
1a890 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
1a8a0 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e  t can.** be boun
1a8b0 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
1a8c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
1a8d0 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
1a8e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1a8f0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
1a900 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
1a910 67 65 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f  gers.</dd>.** </
1a920 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
1a930 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
1a940 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1a950 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
1a960 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1a970 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
1a980 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
1a990 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1a9a0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
1a9b0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
1a9c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
1a9d0 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
1a9e0 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
1a9f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1aa00 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
1aa10 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
1aa20 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1aa30 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
1aa40 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
1aa50 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1aa60 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
1aa70 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
1aa80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1aa90 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
1aaa0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
1aab0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1aac0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1aad0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
1aae0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1aaf0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1ab00 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
1ab10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ab20 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
1ab30 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
1ab40 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
1ab50 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
1ab60 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48  SQL Statement {H
1ab70 31 33 30 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a  13010} <S10000>.
1ab80 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
1ab90 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
1aba0 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  iler}.**.** To e
1abb0 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
1abc0 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
1abd0 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
1abe0 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
1abf0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
1ac00 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
1ac10 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
1ac20 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1ac30 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
1ac40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ac50 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
1ac60 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
1ac70 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
1ac80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1ac90 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1aca0 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
1acb0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
1acc0 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
1acd0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
1ace0 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
1acf0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
1ad00 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
1ad10 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
1ad20 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
1ad30 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
1ad40 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
1ad50 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
1ad60 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
1ad70 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
1ad80 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
1ad90 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
1ada0 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
1adb0 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
1adc0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1add0 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
1ade0 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66  UTF-16..**.** If
1adf0 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
1ae00 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ent is less than
1ae10 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
1ae20 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
1ae30 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
1ae40 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20   terminator. If 
1ae50 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
1ae60 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
1ae70 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1ae80 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
1ae90 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
1aea0 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73  .  When nByte is
1aeb0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
1aec0 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
1aed0 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
1aee0 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
1aef0 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
1af00 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
1af10 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
1af20 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
1af30 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
1af40 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
1af50 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
1af60 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
1af70 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
1af80 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
1af90 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
1afa0 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
1afb0 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
1afc0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
1afd0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
1afe0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
1aff0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
1b000 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1b010 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
1b020 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
1b030 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a  minator bytes..*
1b040 2a 0a 2a 2a 20 49 66 20 70 7a 54 61 69 6c 20 69  *.** If pzTail i
1b050 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
1b060 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
1b070 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
1b080 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
1b090 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
1b0a0 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
1b0b0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
1b0c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1b0d0 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
1b0e0 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
1b0f0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
1b100 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
1b110 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
1b120 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
1b130 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70  piled..**.** *pp
1b140 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
1b150 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
1b160 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
1b170 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
1b180 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
1b190 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1b1a0 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65  step()].  If the
1b1b0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
1b1c0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
1b1d0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74  * to NULL.  If t
1b1e0 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
1b1f0 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
1b200 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
1b210 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
1b220 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
1b230 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
1b240 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
1b250 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
1b260 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
1b270 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
1b280 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
1b290 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
1b2a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1b2b0 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
1b2c0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
1b2d0 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53   with it..** ppS
1b2e0 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e  tmt may not be N
1b2f0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75  ULL..**.** On su
1b300 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f  ccess, [SQLITE_O
1b310 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20  K] is returned, 
1b320 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
1b330 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
1b340 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
1b350 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1b360 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
1b370 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1b380 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
1b390 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
1b3a0 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
1b3b0 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
1b3c0 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
1b3d0 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
1b3e0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1b3f0 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
1b400 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
1b410 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74  ouraged..** In t
1b420 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
1b430 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
1b440 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
1b450 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
1b460 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
1b470 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
1b480 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
1b490 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
1b4a0 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
1b4b0 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
1b4c0 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
1b4d0 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
1b4e0 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  a differently in
1b4f0 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a   two ways:.**.**
1b500 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
1b510 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1b520 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
1b530 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
1b540 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
1b550 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
1b560 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
1b570 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1b580 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
1b590 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
1b5a0 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
1b5b0 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
1b5c0 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49  run it again.  I
1b5d0 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73  f the schema has
1b5e0 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61   changed in.** a
1b5f0 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20   way that makes 
1b600 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f  the statement no
1b610 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b   longer valid, [
1b620 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1b630 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65  will still.** re
1b640 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  turn [SQLITE_SCH
1b650 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b  EMA].  But unlik
1b660 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
1b670 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53  avior, [SQLITE_S
1b680 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77  CHEMA] is.** now
1b690 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20   a fatal error. 
1b6a0 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
1b6b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1b6c0 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d  again will not m
1b6d0 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  ake the.** error
1b6e0 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a   go away.  Note:
1b6f0 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   use [sqlite3_er
1b700 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20  rmsg()] to find 
1b710 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74  the text.** of t
1b720 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72  he parsing error
1b730 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e   that results in
1b740 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45   an [SQLITE_SCHE
1b750 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c  MA] return..** <
1b760 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
1b770 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  ** When an error
1b780 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
1b790 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
1b7a0 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
1b7b0 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
1b7c0 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
1b7d0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
1b7e0 64 65 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 63  des].  The legac
1b7f0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
1b800 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
1b810 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
1b820 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
1b830 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
1b840 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
1b850 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20  * and you would 
1b860 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
1b870 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
1b880 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1b890 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66  in order.** to f
1b8a0 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
1b8b0 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
1b8c0 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
1b8d0 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
1b8e0 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
1b8f0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
1b900 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
1b910 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
1b920 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
1b930 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  li>.** </ol>.**.
1b940 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1b950 0a 2a 2a 20 5b 48 31 33 30 31 31 5d 20 5b 48 31  .** [H13011] [H1
1b960 33 30 31 32 5d 20 5b 48 31 33 30 31 33 5d 20 5b  3012] [H13013] [
1b970 48 31 33 30 31 34 5d 20 5b 48 31 33 30 31 35 5d  H13014] [H13015]
1b980 20 5b 48 31 33 30 31 36 5d 20 5b 48 31 33 30 31   [H13016] [H1301
1b990 39 5d 20 5b 48 31 33 30 32 31 5d 0a 2a 2a 0a 2a  9] [H13021].**.*
1b9a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  /.int sqlite3_pr
1b9b0 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
1b9c0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1b9d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1b9e0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1b9f0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
1ba00 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1ba10 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
1ba20 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1ba30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1ba40 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1ba50 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1ba60 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1ba70 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1ba80 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1ba90 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1baa0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
1bab0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1bac0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1bad0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1bae0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1baf0 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
1bb00 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1bb10 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1bb20 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1bb30 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1bb40 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1bb50 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
1bb60 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1bb70 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1bb80 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1bb90 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1bba0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1bbb0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1bbc0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1bbd0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1bbe0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
1bbf0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1bc00 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1bc10 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1bc20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1bc30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1bc40 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1bc50 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1bc60 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1bc70 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1bc80 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1bc90 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1bca0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
1bcb0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1bcc0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1bcd0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1bce0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1bcf0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1bd00 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1bd10 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1bd20 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1bd30 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
1bd40 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1bd50 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1bd60 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1bd70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1bd80 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
1bd90 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1bda0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1bdb0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1bdc0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
1bdd0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1bde0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
1bdf0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1be00 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1be10 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1be20 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1be30 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1be40 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1be50 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1be60 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1be70 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
1be80 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1be90 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1bea0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1beb0 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
1bec0 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
1bed0 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
1bee0 53 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48 31  SQL {H13100} <H1
1bef0 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  3000>.**.** This
1bf00 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
1bf10 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
1bf20 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
1bf30 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
1bf40 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
1bf50 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
1bf60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1bf70 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
1bf80 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
1bf90 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
1bfa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1bfb0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
1bfc0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1bfd0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ()]..**.** Requi
1bfe0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1bff0 31 30 31 5d 20 5b 48 31 33 31 30 32 5d 20 5b 48  101] [H13102] [H
1c000 31 33 31 30 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20  13103].*/.const 
1c010 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
1c020 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
1c030 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1c040 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
1c050 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
1c060 20 4f 62 6a 65 63 74 20 7b 48 31 35 30 30 30 7d   Object {H15000}
1c070 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59   <S20200>.** KEY
1c080 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
1c090 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
1c0a0 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
1c0b0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
1c0c0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
1c0d0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
1c0e0 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
1c0f0 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
1c100 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
1c110 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
1c120 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
1c130 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
1c140 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
1c150 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
1c160 73 2e 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64  s. Values stored
1c170 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
1c180 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
1c190 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
1c1a0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
1c1b0 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
1c1c0 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
1c1d0 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
1c1e0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
1c1f0 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
1c200 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
1c210 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
1c220 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
1c230 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
1c240 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
1c250 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
1c260 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
1c270 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
1c280 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
1c290 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1c2a0 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
1c2b0 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
1c2c0 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
1c2d0 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
1c2e0 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
1c2f0 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
1c300 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
1c310 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
1c320 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
1c330 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
1c340 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
1c350 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
1c360 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
1c370 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72  s held.  A inter
1c380 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
1c390 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
1c3a0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1c3b0 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
1c3c0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
1c3d0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
1c3e0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1c3f0 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
1c400 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
1c410 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
1c420 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
1c430 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1c440 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
1c450 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
1c460 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
1c470 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
1c480 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
1c490 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
1c4a0 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
1c4b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
1c4c0 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
1c4d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
1c4e0 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
1c4f0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
1c500 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
1c510 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
1c520 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
1c530 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1c540 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
1c550 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
1c560 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
1c570 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
1c580 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
1c590 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
1c5a0 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
1c5b0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
1c5c0 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
1c5d0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62 65  ction between be
1c5e0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
1c5f0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
1c600 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
1c610 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
1c620 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
1c630 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
1c640 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
1c650 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
1c660 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
1c670 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
1c680 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1c690 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
1c6a0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
1c6b0 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
1c6c0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20  otected..** The 
1c6d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1c6e0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
1c6f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
1c700 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
1c710 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
1c720 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
1c730 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1c740 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
1c750 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
1c760 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
1c770 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1c780 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
1c790 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1c7a0 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
1c7b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
1c7c0 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
1c7d0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
1c7e0 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
1c7f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1c800 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
1c810 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
1c820 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
1c830 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
1c840 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
1c850 62 6a 65 63 74 20 7b 48 31 36 30 30 31 7d 20 3c  bject {H16001} <
1c860 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
1c870 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
1c880 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
1c890 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
1c8a0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
1c8b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
1c8c0 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65  bject.  A pointe
1c8d0 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
1c8e0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
1c8f0 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
1c900 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
1c910 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1c920 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1c930 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
1c940 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
1c950 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
1c960 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
1c970 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
1c980 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
1c990 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
1c9a0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
1c9b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
1c9c0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1c9d0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
1c9e0 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
1c9f0 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
1ca00 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
1ca10 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
1ca20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
1ca30 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
1ca40 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
1ca50 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
1ca60 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1ca70 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
1ca80 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
1ca90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
1caa0 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
1cab0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
1cac0 65 6e 74 73 20 7b 48 31 33 35 30 30 7d 20 3c 53  ents {H13500} <S
1cad0 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  70300>.** KEYWOR
1cae0 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
1caf0 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
1cb00 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
1cb10 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
1cb20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
1cb30 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
1cb40 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
1cb50 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
1cb60 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20  *.** In the SQL 
1cb70 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f  strings input to
1cb80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1cb90 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
1cba0 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
1cbb0 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
1cbc0 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
1cbd0 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
1cbe0 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
1cbf0 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
1cc00 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
1cc10 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
1cc20 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
1cc30 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
1cc40 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
1cc50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
1cc60 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
1cc70 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
1cc80 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
1cc90 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
1cca0 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
1ccb0 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
1ccc0 20 69 64 65 6e 74 69 66 65 72 2e 20 20 54 68 65   identifer.  The
1ccd0 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
1cce0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
1ccf0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
1cd00 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
1cd10 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
1cd20 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
1cd30 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
1cd40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1cd50 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
1cd60 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  d here..**.** Th
1cd70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1cd80 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1cd90 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1cda0 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
1cdb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1cdc0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1cdd0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
1cde0 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
1cdf0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1ce00 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
1ce10 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
1ce20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
1ce30 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
1ce40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
1ce50 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66   set..** The lef
1ce60 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
1ce70 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
1ce80 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65   of 1.  When the
1ce90 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
1cea0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
1ceb0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
1cec0 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
1ced0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
1cee0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
1cef0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
1cf00 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
1cf10 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e  rence..** The in
1cf20 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
1cf30 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
1cf40 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
1cf50 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1cf60 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1cf70 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
1cf80 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64  esired.  The ind
1cf90 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
1cfa0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
1cfb0 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
1cfc0 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75  .** The NNN valu
1cfd0 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
1cfe0 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
1cff0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
1d000 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
1d010 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
1d020 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
1d030 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
1d040 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
1d050 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
1d060 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
1d070 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1d080 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72  **.** In those r
1d090 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
1d0a0 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
1d0b0 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
1d0c0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
1d0d0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
1d0e0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
1d0f0 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
1d100 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
1d110 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
1d120 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
1d130 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
1d140 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
1d150 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
1d160 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
1d170 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67  gative, the leng
1d180 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
1d190 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
1d1a0 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
1d1b0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
1d1c0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
1d1d0 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 67 75  * The fifth argu
1d1e0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1d1f0 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
1d200 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
1d210 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
1d220 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
1d230 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
1d240 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
1d250 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
1d260 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
1d270 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
1d280 64 20 77 69 74 68 20 69 74 2e 20 49 66 20 74 68  d with it. If th
1d290 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1d2a0 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
1d2b0 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
1d2c0 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
1d2d0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
1d2e0 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
1d2f0 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
1d300 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
1d310 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
1d320 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
1d330 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 66  d..** If the fif
1d340 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
1d350 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
1d360 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
1d370 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
1d380 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
1d390 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
1d3a0 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
1d3b0 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
1d3c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1d3d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
1d3e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1d3f0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
1d400 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
1d410 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
1d420 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
1d430 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
1d440 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75  s.  A zeroblob u
1d450 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
1d460 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
1d470 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
1d480 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
1d490 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
1d4a0 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
1d4b0 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
1d4c0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
1d4d0 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
1d4e0 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
1d4f0 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
1d500 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
1d510 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1d520 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
1d530 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
1d540 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
1d550 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
1d560 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
1d570 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
1d580 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
1d590 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1d5a0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1d5b0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
1d5c0 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71  led after.** [sq
1d5d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d5e0 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72  ()] (and its var
1d5f0 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74  iants) or [sqlit
1d600 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a  e3_reset()] and.
1d610 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74  ** before [sqlit
1d620 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42  e3_step()]..** B
1d630 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
1d640 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
1d650 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1d660 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62   routine..** Unb
1d670 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
1d680 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
1d690 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  as NULL..**.** T
1d6a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1d6b0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1d6c0 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
1d6d0 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a  n error code if.
1d6e0 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  ** anything goes
1d6f0 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45   wrong.  [SQLITE
1d700 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
1d710 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
1d720 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
1d730 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
1d740 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
1d750 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
1d760 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
1d770 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
1d780 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
1d790 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74  ed if these rout
1d7a0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
1d7b0 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20  on a.** virtual 
1d7c0 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20  machine that is 
1d7d0 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20  the wrong state 
1d7e0 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72  or which has alr
1d7f0 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69  eady been finali
1d800 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f  zed..** Detectio
1d810 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75  n of misuse is u
1d820 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c  nreliable.  Appl
1d830 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
1d840 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  not depend.** on
1d850 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72   SQLITE_MISUSE r
1d860 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f  eturns.  SQLITE_
1d870 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64  MISUSE is intend
1d880 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61  ed to indicate a
1d890 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f  .** a logic erro
1d8a0 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61  r in the applica
1d8b0 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65  tion.  Future ve
1d8c0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1d8d0 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20   might.** panic 
1d8e0 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75  rather than retu
1d8f0 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
1d900 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1d910 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1d920 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1d930 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1d940 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1d950 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
1d960 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1d970 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
1d980 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1d990 3a 0a 2a 2a 20 5b 48 31 33 35 30 36 5d 20 5b 48  :.** [H13506] [H
1d9a0 31 33 35 30 39 5d 20 5b 48 31 33 35 31 32 5d 20  13509] [H13512] 
1d9b0 5b 48 31 33 35 31 35 5d 20 5b 48 31 33 35 31 38  [H13515] [H13518
1d9c0 5d 20 5b 48 31 33 35 32 31 5d 20 5b 48 31 33 35  ] [H13521] [H135
1d9d0 32 34 5d 20 5b 48 31 33 35 32 37 5d 0a 2a 2a 20  24] [H13527].** 
1d9e0 5b 48 31 33 35 33 30 5d 20 5b 48 31 33 35 33 33  [H13530] [H13533
1d9f0 5d 20 5b 48 31 33 35 33 36 5d 20 5b 48 31 33 35  ] [H13536] [H135
1da00 33 39 5d 20 5b 48 31 33 35 34 32 5d 20 5b 48 31  39] [H13542] [H1
1da10 33 35 34 35 5d 20 5b 48 31 33 35 34 38 5d 20 5b  3545] [H13548] [
1da20 48 31 33 35 35 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e  H13551].**.*/.in
1da30 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
1da40 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
1da50 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
1da60 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
1da70 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
1da80 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
1da90 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
1daa0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
1dab0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1dac0 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
1dad0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
1dae0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1daf0 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
1db00 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
1db10 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
1db20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
1db30 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
1db40 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
1db50 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
1db60 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1db70 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
1db80 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
1db90 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
1dba0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
1dbb0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1dbc0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1dbd0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
1dbe0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
1dbf0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
1dc00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1dc10 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
1dc20 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
1dc30 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
1dc40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1dc50 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
1dc60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
1dc70 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
1dc80 6d 65 74 65 72 73 20 7b 48 31 33 36 30 30 7d 20  meters {H13600} 
1dc90 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70300>.**.** T
1dca0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
1dcb0 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
1dcc0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
1dcd0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
1dce0 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
1dcf0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
1dd00 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
1dd10 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
1dd20 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
1dd30 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
1dd40 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
1dd50 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
1dd60 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
1dd70 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
1dd80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1dd90 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
1dda0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
1ddb0 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
1ddc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
1ddd0 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
1dde0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
1ddf0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
1de00 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
1de10 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
1de20 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
1de30 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
1de40 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
1de50 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
1de60 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
1de70 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
1de80 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75  f the ?NNN are u
1de90 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
1dea0 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
1deb0 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   list..**.** See
1dec0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1ded0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1dee0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
1def0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1df00 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
1df10 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1df20 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1df30 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65  dex()]..**.** Re
1df40 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
1df50 48 31 33 36 30 31 5d 0a 2a 2f 0a 69 6e 74 20 73  H13601].*/.int s
1df60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1df70 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
1df80 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1df90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
1dfa0 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
1dfb0 6d 65 74 65 72 20 7b 48 31 33 36 32 30 7d 20 3c  meter {H13620} <
1dfc0 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S70300>.**.** Th
1dfd0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
1dfe0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1dff0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1e000 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72  n-th.** [SQL par
1e010 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 72  ameter] in a [pr
1e020 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e030 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ]..** SQL parame
1e040 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
1e050 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
1e060 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
1e070 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
1e080 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
1e090 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
1e0a0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
1e0b0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
1e0c0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
1e0d0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
1e0e0 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
1e0f0 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
1e100 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
1e110 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
1e120 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61   the name..** Pa
1e130 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
1e140 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
1e150 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
1e160 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
1e170 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73  e.** and are als
1e180 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  o referred to as
1e190 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
1e1a0 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54  meters"..**.** T
1e1b0 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
1e1c0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
1e1d0 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
1e1e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76  ..**.** If the v
1e1f0 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66  alue n is out of
1e200 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
1e210 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   n-th parameter 
1e220 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
1e230 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
1e240 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75  urned.  The retu
1e250 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
1e260 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
1e270 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
1e280 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
1e290 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
1e2a0 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
1e2b0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
1e2c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e2d0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
1e2e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1e2f0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
1e300 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
1e310 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
1e320 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
1e330 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1e340 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
1e350 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1e360 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1e370 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65  dex()]..**.** Re
1e380 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
1e390 48 31 33 36 32 31 5d 0a 2a 2f 0a 63 6f 6e 73 74  H13621].*/.const
1e3a0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
1e3b0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1e3c0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
1e3d0 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
1e3e0 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
1e3f0 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
1e400 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20  th A Given Name 
1e410 7b 48 31 33 36 34 30 7d 20 3c 53 37 30 33 30 30  {H13640} <S70300
1e420 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  >.**.** Return t
1e430 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
1e440 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
1e450 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68  en its name.  Th
1e460 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
1e470 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
1e480 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
1e490 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
1e4a0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1e4b0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
1e4c0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
1e4d0 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65   A zero.** is re
1e4e0 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
1e4f0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
1e500 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70  is found.  The p
1e510 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
1e520 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
1e530 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
1e540 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
1e550 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
1e560 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
1e570 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
1e580 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1e590 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
1e5a0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
1e5b0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
1e5c0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
1e5d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1e5e0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
1e5f0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1e600 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1e610 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
1e620 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
1e630 20 5b 48 31 33 36 34 31 5d 0a 2a 2f 0a 69 6e 74   [H13641].*/.int
1e640 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
1e650 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
1e660 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
1e670 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
1e680 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e690 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
1e6a0 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
1e6b0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31  ed Statement {H1
1e6c0 33 36 36 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3660} <S70300>.*
1e6d0 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f  *.** Contrary to
1e6e0 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
1e6f0 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
1e700 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
1e710 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
1e720 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1e730 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
1e740 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
1e750 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65  atement]..** Use
1e760 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
1e770 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
1e780 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
1e790 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  LL..**.** Requir
1e7a0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36  ements:.** [H136
1e7b0 36 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  61].*/.int sqlit
1e7c0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
1e7d0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
1e7e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e7f0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
1e800 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
1e810 20 53 65 74 20 7b 48 31 33 37 31 30 7d 20 3c 53   Set {H13710} <S
1e820 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74  10700>.**.** Ret
1e830 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
1e840 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
1e850 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
1e860 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
1e870 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e880 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  nt]. This routin
1e890 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
1e8a0 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
1e8b0 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
1e8c0 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
1e8d0 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
1e8e0 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
1e8f0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
1e900 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 31 31 5d  nts:.** [H13711]
1e910 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1e920 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
1e930 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
1e940 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e950 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
1e960 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
1e970 20 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30   {H13720} <S1070
1e980 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
1e990 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
1e9a0 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
1e9b0 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
1e9c0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
1e9d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
1e9e0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
1e9f0 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74  ment.  The sqlit
1ea00 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
1ea10 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
1ea20 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1ea30 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
1ea40 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1ea50 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
1ea60 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
1ea70 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1ea80 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
1ea90 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
1eaa0 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66  6 string.  The f
1eab0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
1eac0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
1ead0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
1eae0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
1eaf0 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
1eb00 6d 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64  ment. The second
1eb10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1eb20 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
1eb30 65 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73  er.  The leftmos
1eb40 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
1eb50 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er 0..**.** The 
1eb60 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
1eb70 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
1eb80 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
1eb90 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1eba0 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
1ebb0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
1ebc0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
1ebd0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
1ebe0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
1ebf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
1ec00 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
1ec10 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
1ec20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
1ec30 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65  .**.** If sqlite
1ec40 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
1ec50 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
1ec60 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
1ec70 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
1ec80 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
1ec90 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
1eca0 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
1ecb0 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
1ecc0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
1ecd0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
1ece0 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
1ecf0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
1ed00 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
1ed10 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
1ed20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
1ed30 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
1ed40 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
1ed50 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
1ed60 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
1ed70 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
1ed80 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
1ed90 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
1eda0 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
1edb0 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
1edc0 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 52  he next..**.** R
1edd0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1ede0 5b 48 31 33 37 32 31 5d 20 5b 48 31 33 37 32 33  [H13721] [H13723
1edf0 5d 20 5b 48 31 33 37 32 34 5d 20 5b 48 31 33 37  ] [H13724] [H137
1ee00 32 35 5d 20 5b 48 31 33 37 32 36 5d 20 5b 48 31  25] [H13726] [H1
1ee10 33 37 32 37 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63  3727].*/.const c
1ee20 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
1ee30 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
1ee40 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
1ee50 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1ee60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1ee70 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
1ee80 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
1ee90 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
1eea0 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
1eeb0 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37  ery Result {H137
1eec0 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  40} <S10700>.**.
1eed0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1eee0 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
1eef0 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77  s to determine w
1ef00 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68  hat column of wh
1ef10 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77  at.** table in w
1ef20 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61 20  hich database a 
1ef30 72 65 73 75 6c 74 20 6f 66 20 61 20 5b 53 45 4c  result of a [SEL
1ef40 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63  ECT] statement c
1ef50 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68  omes from..** Th
1ef60 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1ef70 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
1ef80 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
1ef90 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
1efa0 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
1efb0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
1efc0 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f    The _database_
1efd0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1efe0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1eff0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
1f000 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
1f010 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
1f020 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
1f030 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
1f040 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
1f050 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65   name..** The re
1f060 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
1f070 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
1f080 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f090 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
1f0a0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
1f0b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1f0c0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
1f0d0 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
1f0e0 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
1f0f0 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
1f100 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
1f110 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65  .** The names re
1f120 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
1f130 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
1f140 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
1f150 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
1f160 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
1f170 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
1f180 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1f190 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20  following calls 
1f1a0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
1f1b0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68  tatement]..** Th
1f1c0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
1f1d0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
1f1e0 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63   about the Nth c
1f1f0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
1f200 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
1f210 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
1f220 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
1f230 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
1f240 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f  ** If the Nth co
1f250 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
1f260 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
1f270 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
1f280 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
1f290 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
1f2a0 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
1f2b0 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
1f2c0 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
1f2d0 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f 75  NULL.  These rou
1f2e0 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
1f2f0 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
1f300 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1f310 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
1f320 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  rs.  Otherwise, 
1f330 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
1f340 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
1f350 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
1f360 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75  able.** and colu
1f370 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
1f380 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
1f390 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
1f3a0 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c  **.** As with al
1f3b0 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
1f3c0 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66  PIs, those postf
1f3d0 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20 72  ixed with "16" r
1f3e0 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
1f3f0 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c  encoded strings,
1f400 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
1f410 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
1f420 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  8. {END}.**.** T
1f430 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
1f440 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
1f450 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
1f460 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
1f470 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
1f480 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
1f490 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
1f4a0 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
1f4b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35  ed..**.** {A1375
1f4c0 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  1}.** If two or 
1f4d0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
1f4e0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
1f4f0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1f500 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
1f510 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
1f520 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
1f530 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
1f540 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
1f550 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
1f560 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ined..**.** Requ
1f570 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1f580 33 37 34 31 5d 20 5b 48 31 33 37 34 32 5d 20 5b  3741] [H13742] [
1f590 48 31 33 37 34 33 5d 20 5b 48 31 33 37 34 34 5d  H13743] [H13744]
1f5a0 20 5b 48 31 33 37 34 35 5d 20 5b 48 31 33 37 34   [H13745] [H1374
1f5b0 36 5d 20 5b 48 31 33 37 34 38 5d 0a 2a 2a 0a 2a  6] [H13748].**.*
1f5c0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
1f5d0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
1f5e0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
1f5f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
1f600 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
1f610 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
1f620 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
1f630 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
1f640 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
1f650 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
1f660 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
1f670 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
1f680 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
1f690 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
1f6a0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
1f6b0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
1f6c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1f6d0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
1f6e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
1f6f0 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
1f700 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
1f710 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
1f720 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
1f730 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
1f740 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
1f750 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
1f760 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
1f770 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
1f780 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
1f790 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
1f7a0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
1f7b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1f7c0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
1f7d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
1f7e0 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
1f7f0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
1f800 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f810 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
1f820 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
1f830 65 73 75 6c 74 20 7b 48 31 33 37 36 30 7d 20 3c  esult {H13760} <
1f840 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10700>.**.** Th
1f850 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1f860 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
1f870 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
1f880 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
1f890 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
1f8a0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
1f8b0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
1f8c0 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
1f8d0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
1f8e0 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
1f8f0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
1f900 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
1f910 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
1f920 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
1f930 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
1f940 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
1f950 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20  s returned.  If 
1f960 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
1f970 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
1f980 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
1f990 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
1f9a0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
1f9b0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
1f9c0 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  d..** The return
1f9d0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
1f9e0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
1f9f0 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46  d. {END}.**.** F
1fa00 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
1fa10 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
1fa20 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
1fa30 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
1fa40 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
1fa50 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
1fa60 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
1fa70 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
1fa80 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
1fa90 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
1faa0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
1fab0 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
1fac0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
1fad0 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
1fae0 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
1faf0 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
1fb00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
1fb10 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
1fb20 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
1fb30 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
1fb40 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
1fb50 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20  ime typing.  So 
1fb60 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
1fb70 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
1fb80 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
1fb90 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
1fba0 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
1fbb0 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
1fbc0 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
1fbd0 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
1fbe0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
1fbf0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
1fc00 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
1fc10 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
1fc20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
1fc30 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20  ic.  Type.** is 
1fc40 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1fc50 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
1fc60 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
1fc70 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
1fc80 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
1fc90 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 52   values..**.** R
1fca0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1fcb0 5b 48 31 33 37 36 31 5d 20 5b 48 31 33 37 36 32  [H13761] [H13762
1fcc0 5d 20 5b 48 31 33 37 36 33 5d 0a 2a 2f 0a 63 6f  ] [H13763].*/.co
1fcd0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1fce0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
1fcf0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1fd00 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
1fd10 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1fd20 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
1fd30 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1fd40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1fd50 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
1fd60 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 32   Statement {H132
1fd70 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a  00} <S10000>.**.
1fd80 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
1fd90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1fda0 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
1fdb0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
1fdc0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1fdd0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
1fde0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1fdf0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
1fe00 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
1fe10 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
1fe20 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
1fe30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1fe40 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
1fe50 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
1fe60 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
1fe70 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
1fe80 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
1fe90 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
1fea0 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
1feb0 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
1fec0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
1fed0 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
1fee0 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
1fef0 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
1ff00 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
1ff10 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
1ff20 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
1ff30 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1ff40 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
1ff50 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
1ff60 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
1ff70 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
1ff80 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1ff90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
1ffa0 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
1ffb0 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
1ffc0 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
1ffd0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1ffe0 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
1fff0 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
20000 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
20010 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
20020 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
20030 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67  **.** In the leg
20040 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
20050 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
20060 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
20070 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
20080 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
20090 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
200a0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
200b0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
200c0 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76  ..** With the "v
200d0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
200e0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
200f0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
20100 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
20110 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
20120 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
20130 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51   well..**.** [SQ
20140 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
20150 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
20160 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
20170 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
20180 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
20190 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
201a0 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49  o do its job.  I
201b0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
201c0 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a  is a [COMMIT].**
201d0 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69   or occurs outsi
201e0 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69  de of an explici
201f0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
20200 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72  hen you can retr
20210 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  y the.** stateme
20220 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  nt.  If the stat
20230 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b  ement is not a [
20240 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75  COMMIT] and occu
20250 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65  rs within a.** e
20260 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
20270 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
20280 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
20290 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
202a0 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
202b0 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  g..**.** [SQLITE
202c0 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
202d0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
202e0 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
202f0 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
20300 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
20310 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
20320 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
20330 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
20340 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
20350 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
20360 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
20370 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
20380 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
20390 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
203a0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
203b0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
203c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
203d0 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
203e0 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
203f0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
20400 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
20410 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
20420 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
20430 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
20440 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
20450 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
20460 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
20470 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
20480 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
20490 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
204a0 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
204b0 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
204c0 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
204d0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53  f data..**.** [S
204e0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
204f0 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
20500 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
20510 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
20520 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
20530 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
20540 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
20550 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
20560 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
20570 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
20580 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
20590 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
205a0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
205b0 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67  .** With the leg
205c0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
205d0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
205e0 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
205f0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
20600 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
20610 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
20620 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
20630 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
20640 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
20650 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
20660 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
20670 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
20680 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
20690 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
206a0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
206b0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
206c0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
206d0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
206e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
206f0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
20700 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
20710 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
20720 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
20730 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
20740 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
20750 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
20760 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20770 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
20780 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
20790 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
207a0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
207b0 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
207c0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
207d0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
207e0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
207f0 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
20800 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
20810 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
20820 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20830 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
20840 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
20850 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
20860 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
20870 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  time..**.** <b>G
20880 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
20890 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
208a0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
208b0 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
208c0 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
208d0 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
208e0 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
208f0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
20900 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
20910 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
20920 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
20930 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
20940 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
20950 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
20960 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
20970 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
20980 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
20990 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
209a0 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
209b0 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
209c0 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
209d0 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
209e0 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
209f0 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
20a00 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
20a10 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
20a20 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
20a30 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
20a40 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
20a50 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
20a60 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
20a70 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
20a80 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
20a90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20aa0 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
20ab0 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
20ac0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
20ad0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
20ae0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
20af0 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
20b00 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
20b10 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
20b20 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
20b30 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
20b40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
20b50 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
20b60 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
20b70 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
20b80 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
20b90 73 3a 0a 2a 2a 20 5b 48 31 33 32 30 32 5d 20 5b  s:.** [H13202] [
20ba0 48 31 35 33 30 34 5d 20 5b 48 31 35 33 30 36 5d  H15304] [H15306]
20bb0 20 5b 48 31 35 33 30 38 5d 20 5b 48 31 35 33 31   [H15308] [H1531
20bc0 30 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  0].*/.int sqlite
20bd0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
20be0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
20bf0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
20c00 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
20c10 65 73 75 6c 74 20 73 65 74 20 7b 48 31 33 37 37  esult set {H1377
20c20 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
20c30 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e 75  * Returns the nu
20c40 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69  mber of values i
20c50 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
20c60 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
20c70 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  set..**.** Requi
20c80 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
20c90 37 37 31 5d 20 5b 48 31 33 37 37 32 5d 0a 2a 2f  771] [H13772].*/
20ca0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
20cb0 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
20cc0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
20cd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
20ce0 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
20cf0 79 70 65 73 20 7b 48 31 30 32 36 35 7d 20 3c 53  ypes {H10265} <S
20d00 31 30 31 31 30 3e 3c 53 31 30 31 32 30 3e 0a 2a  10110><S10120>.*
20d10 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
20d20 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48  TE_TEXT.**.** {H
20d30 31 30 32 36 36 7d 20 45 76 65 72 79 20 76 61 6c  10266} Every val
20d40 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
20d50 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
20d60 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
20d70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
20d80 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
20d90 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
20da0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
20db0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
20dc0 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
20dd0 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
20de0 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
20df0 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a  ** </ul> {END}.*
20e00 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
20e10 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
20e20 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
20e30 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
20e40 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
20e50 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
20e60 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
20e70 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
20e80 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
20e90 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
20ea0 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
20eb0 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
20ec0 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
20ed0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
20ee0 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
20ef0 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
20f00 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
20f10 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
20f20 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
20f30 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
20f40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
20f50 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
20f60 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
20f70 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
20f80 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
20f90 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
20fa0 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
20fb0 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
20fc0 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
20fd0 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
20fe0 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
20ff0 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
21000 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
21010 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
21020 72 79 20 7b 48 31 33 38 30 30 7d 20 3c 53 31 30  ry {H13800} <S10
21030 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  700>.** KEYWORDS
21040 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
21050 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
21060 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
21070 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c   form the "resul
21080 74 20 73 65 74 20 71 75 65 72 79 22 20 69 6e 74  t set query" int
21090 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
210a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
210b0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
210c0 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
210d0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
210e0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
210f0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
21100 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
21110 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
21120 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
21130 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
21140 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
21150 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
21160 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
21170 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
21180 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
21190 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
211a0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
211b0 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
211c0 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
211d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
211e0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
211f0 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
21200 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
21210 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
21220 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74 6d  rned.  The leftm
21230 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
21240 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
21250 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
21260 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
21270 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
21280 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
21290 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
212a0 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
212b0 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
212c0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
212d0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
212e0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
212f0 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
21300 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
21310 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
21320 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
21330 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
21340 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
21350 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
21360 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
21370 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
21380 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
21390 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
213a0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
213b0 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
213c0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
213d0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
213e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
213f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
21400 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
21410 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
21420 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
21430 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
21440 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
21450 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
21460 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
21470 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
21480 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
21490 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
214a0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
214b0 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
214c0 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
214d0 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
214e0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
214f0 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
21500 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
21510 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
21520 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
21530 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21540 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
21550 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
21560 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
21570 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
21580 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
21590 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
215a0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
215b0 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  .  The returned 
215c0 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
215d0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
215e0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
215f0 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
21600 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
21610 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
21620 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
21630 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
21640 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
21650 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
21660 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
21670 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
21680 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
21690 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
216a0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
216b0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
216c0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
216d0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
216e0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
216f0 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
21700 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
21710 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
21720 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
21730 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
21740 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
21750 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
21760 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
21770 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
21780 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
21790 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
217a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
217b0 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
217c0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
217d0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
217e0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
217f0 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65  tring..** If the
21800 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
21810 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
21820 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21830 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
21840 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
21850 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
21860 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
21870 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
21880 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
21890 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
218a0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
218b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
218c0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
218d0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
218e0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
218f0 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
21900 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
21910 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
21920 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
21930 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c  ring..** The val
21940 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  ue returned does
21950 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
21960 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
21970 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
21980 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46  f the string.  F
21990 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
219a0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
219b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
219c0 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
219d0 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
219e0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
219f0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69  ters..**.** Stri
21a00 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
21a10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21a20 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
21a30 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
21a40 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
21a50 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
21a60 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e  ways zero termin
21a70 61 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 72  ated.  The retur
21a80 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
21a90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21aa0 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
21ab0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
21ac0 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  an arbitrary.** 
21ad0 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c  pointer, possibl
21ae0 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  y even a NULL po
21af0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
21b00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21b10 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e  bytes16() routin
21b20 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
21b30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21b40 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65  ytes().** but le
21b50 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  aves the result 
21b60 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  in UTF-16 in nat
21b70 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
21b80 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e  nstead of UTF-8.
21b90 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72  .** The zero ter
21ba0 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69  minator is not i
21bb0 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20  ncluded in this 
21bc0 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  count..**.** The
21bd0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
21be0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
21bf0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
21c00 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
21c10 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
21c20 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
21c30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
21c40 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
21c50 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
21c60 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
21c70 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
21c80 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
21c90 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
21ca0 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
21cb0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
21cc0 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
21cd0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
21ce0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
21cf0 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
21d00 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
21d10 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
21d20 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
21d30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
21d40 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
21d50 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
21d60 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
21d70 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
21d80 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
21d90 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
21da0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
21db0 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
21dc0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
21dd0 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
21de0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
21df0 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
21e00 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
21e10 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
21e20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
21e30 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
21e40 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
21e50 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
21e60 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
21e70 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
21e80 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
21e90 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  y.  The followin
21ea0 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
21eb0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
21ec0 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
21ed0 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
21ee0 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
21ef0 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
21f00 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
21f10 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
21f20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
21f30 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
21f40 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
21f50 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
21f60 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
21f70 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
21f80 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
21f90 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
21fa0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
21fb0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
21fc0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
21fd0 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
21fe0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
21ff0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
22000 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
22010 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
22020 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
22030 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
22040 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
22050 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
22060 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
22070 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
22080 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
22090 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
220a0 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
220b0 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
220c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
220d0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
220e0 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
220f0 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
22100 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
22110 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
22120 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
22130 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69   from float to i
22140 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
22150 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
22160 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
22170 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
22180 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
22190 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
221a0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
221b0 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c   <td> Same as FL
221c0 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  OAT->TEXT.** <tr
221d0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
221e0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
221f0 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a  d> Use atoi().**
22200 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
22210 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
22220 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28    <td> Use atof(
22230 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
22240 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
22250 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
22260 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
22270 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
22280 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
22290 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
222a0 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a  en use atoi().**
222b0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
222c0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
222d0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
222e0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
222f0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
22300 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
22310 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
22320 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
22330 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
22340 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
22350 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
22360 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f  ** The table abo
22370 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e  ve makes referen
22380 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43  ce to standard C
22390 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f   library functio
223a0 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64  ns atoi().** and
223b0 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65   atof().  SQLite
223c0 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79   does not really
223d0 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74   use these funct
223e0 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74  ions.  It has it
223f0 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c  s.** own equival
22400 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
22410 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
22420 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
22430 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
22440 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
22450 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
22460 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
22470 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
22480 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
22490 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
224a0 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
224b0 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
224c0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
224d0 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
224e0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
224f0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
22500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
22510 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
22520 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
22530 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
22540 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
22550 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
22560 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
22570 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
22580 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
22590 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
225a0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
225b0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
225c0 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
225d0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
225e0 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
225f0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
22600 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
22610 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
22620 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
22630 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
22640 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
22650 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
22660 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
22670 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
22680 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
22690 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
226a0 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
226b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
226c0 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
226d0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
226e0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
226f0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
22700 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
22710 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
22720 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
22730 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
22740 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
22750 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
22760 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
22770 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
22780 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
22790 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
227a0 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
227b0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
227c0 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
227d0 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
227e0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
227f0 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
22800 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
22810 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
22820 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
22830 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
22840 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
22850 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
22860 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
22870 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c  r points to will
22880 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
22890 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
228a0 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
228b0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
228c0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
228d0 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
228e0 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
228f0 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
22900 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
22910 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
22920 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
22930 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
22940 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
22950 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
22960 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
22970 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
22980 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
22990 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
229a0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
229b0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
229c0 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
229d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
229e0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
229f0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
22a00 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
22a10 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
22a20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
22a30 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
22a40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22a50 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
22a60 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
22a70 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
22a80 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
22a90 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
22aa0 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
22ab0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22ac0 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
22ad0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
22ae0 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
22af0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
22b00 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
22b10 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
22b20 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
22b30 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
22b40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
22b50 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
22b60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
22b70 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
22b80 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
22b90 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
22ba0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
22bb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
22bc0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
22bd0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
22be0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
22bf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
22c00 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
22c10 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
22c20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
22c30 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
22c40 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
22c50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
22c60 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
22c70 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
22c80 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
22c90 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
22ca0 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
22cb0 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
22cc0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
22cd0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
22ce0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
22cf0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
22d00 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
22d10 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61    The memory spa
22d20 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
22d30 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
22d40 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
22d50 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
22d60 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
22d70 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
22d80 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74  turned.** [sqlit
22d90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
22da0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
22db0 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
22dc0 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
22dd0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
22de0 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   If a memory all
22df0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
22e00 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
22e10 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
22e20 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
22e30 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
22e40 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
22e50 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
22e60 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
22e70 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
22e80 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
22e90 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
22ea0 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
22eb0 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
22ec0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
22ed0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
22ee0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
22ef0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
22f00 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
22f10 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 38 30 33 5d  nts:.** [H13803]
22f20 20 5b 48 31 33 38 30 36 5d 20 5b 48 31 33 38 30   [H13806] [H1380
22f30 39 5d 20 5b 48 31 33 38 31 32 5d 20 5b 48 31 33  9] [H13812] [H13
22f40 38 31 35 5d 20 5b 48 31 33 38 31 38 5d 20 5b 48  815] [H13818] [H
22f50 31 33 38 32 31 5d 20 5b 48 31 33 38 32 34 5d 0a  13821] [H13824].
22f60 2a 2a 20 5b 48 31 33 38 32 37 5d 20 5b 48 31 33  ** [H13827] [H13
22f70 38 33 30 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  830].*/.const vo
22f80 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
22f90 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
22fa0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
22fb0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
22fc0 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
22fd0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
22fe0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
22ff0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
23000 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
23010 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
23020 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23030 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
23040 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
23050 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
23060 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
23070 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
23080 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
23090 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
230a0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
230b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
230c0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
230d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
230e0 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
230f0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
23100 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
23110 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
23120 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
23130 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
23140 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
23150 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
23160 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
23170 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
23180 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
23190 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
231a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
231b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
231c0 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
231d0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
231e0 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 37 30  ct {H13300} <S70
231f0 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a  300><S30100>.**.
23200 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66  ** The sqlite3_f
23210 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
23220 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
23230 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
23240 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
23250 2a 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65  * If the stateme
23260 6e 74 20 77 61 73 20 65 78 65 63 75 74 65 64 20  nt was executed 
23270 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20  successfully or 
23280 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20  not executed at 
23290 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  all, then.** SQL
232a0 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
232b0 65 64 2e 20 49 66 20 65 78 65 63 75 74 69 6f 6e  ed. If execution
232c0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
232d0 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e  t failed then an
232e0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
232f0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
23300 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
23310 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  urned..**.** Thi
23320 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
23330 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
23340 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20  oint during the 
23350 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
23360 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
23370 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68  atement].  If th
23380 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  e virtual machin
23390 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d  e has not.** com
233a0 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
233b0 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   when this routi
233c0 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  ne is called, th
233d0 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e  at is like.** en
233e0 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72  countering an er
233f0 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ror or an [sqlit
23400 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69  e3_interrupt | i
23410 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e  nterrupt]..** In
23420 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73  complete updates
23430 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62   may be rolled b
23440 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74  ack and transact
23450 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a  ions canceled,.*
23460 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  * depending on t
23470 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  he circumstances
23480 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72  , and the.** [er
23490 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e  ror code] return
234a0 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49  ed will be [SQLI
234b0 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a  TE_ABORT]..**.**
234c0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
234d0 2a 20 5b 48 31 31 33 30 32 5d 20 5b 48 31 31 33  * [H11302] [H113
234e0 30 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  04].*/.int sqlit
234f0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
23500 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
23510 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23520 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
23530 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
23540 6a 65 63 74 20 7b 48 31 33 33 33 30 7d 20 3c 53  ject {H13330} <S
23550 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  70300>.**.** The
23560 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
23570 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
23580 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
23590 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
235a0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
235b0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
235c0 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
235d0 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
235e0 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61  ..** Any SQL sta
235f0 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
23600 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
23610 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
23620 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
23630 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
23640 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
23650 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
23660 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
23670 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
23680 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
23690 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
236a0 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  ngs..**.** {H113
236b0 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  32} The [sqlite3
236c0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
236d0 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
236e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
236f0 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20  ent] S.**       
23700 20 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62     back to the b
23710 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
23720 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b  program..**.** {
23730 48 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d  H11334} If the m
23740 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
23750 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
23760 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
23770 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
23780 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
23790 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
237a0 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
237b0 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20  _DONE],.**      
237c0 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74      or if [sqlit
237d0 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
237e0 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
237f0 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
23800 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
23810 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
23820 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
23830 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  TE_OK]..**.** {H
23840 31 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d 6f  11336} If the mo
23850 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
23860 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
23870 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  S)] for the.**  
23880 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
23890 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
238a0 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
238b0 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  r, then.**      
238c0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
238d0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
238e0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
238f0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
23900 2a 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20 5b  * {H11338} The [
23910 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
23920 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
23930 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
23940 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20  values.**       
23950 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74     of any [sqlit
23960 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
23970 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
23980 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23990 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  t] S..*/.int sql
239a0 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
239b0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
239c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
239d0 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
239e0 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
239f0 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 32 30  ns {H16100} <S20
23a00 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
23a10 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
23a20 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
23a30 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
23a40 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
23a50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
23a60 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
23a70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
23a80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
23a90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20  **.** These two 
23aa0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
23ab0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
23ac0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
23ad0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
23ae0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
23af0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
23b00 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
23b10 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
23b20 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
23b30 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
23b40 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
23b50 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
23b60 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65  difference betwe
23b70 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73  en the.** two is
23b80 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
23b90 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20   parameter, the 
23ba0 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61  name of the (sca
23bb0 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72  lar) function or
23bc0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69  .** aggregate, i
23bd0 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  s encoded in UTF
23be0 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  -8 for sqlite3_c
23bf0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
23c00 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66   and UTF-16.** f
23c10 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
23c20 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a  e_function16()..
23c30 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
23c40 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
23c50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23c60 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
23c70 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
23c80 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
23c90 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65  ed.  If a single
23ca0 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f   program uses mo
23cb0 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
23cc0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
23cd0 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74  on internally, t
23ce0 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  hen SQL function
23cf0 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20  s must be added 
23d00 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a  individually to.
23d10 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61 73 65  ** each database
23d20 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a   connection..**.
23d30 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
23d40 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
23d50 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
23d60 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
23d70 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
23d80 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e 67  fined.  The leng
23d90 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
23da0 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
23db0 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76   bytes, exclusiv
23dc0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f  e of.** the zero
23dd0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f  -terminator.  No
23de0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
23df0 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
23e00 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a   in bytes, not.*
23e10 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 41  * characters.  A
23e20 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
23e30 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
23e40 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
23e50 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
23e60 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  t in [SQLITE_ERR
23e70 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  OR] being return
23e80 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  ed..**.** The th
23e90 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e  ird parameter (n
23ea0 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e  Arg).** is the n
23eb0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
23ec0 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
23ed0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
23ee0 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
23ef0 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
23f00 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
23f10 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
23f20 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
23f30 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
23f40 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
23f50 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
23f60 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
23f70 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
23f80 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
23f90 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
23fa0 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
23fb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
23fc0 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
23fd0 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
23fe0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
23ff0 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
24000 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72  ..**.** The four
24010 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
24020 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
24030 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
24040 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
24050 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
24060 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
24070 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
24080 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51  ameters.  Any SQ
24090 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
240a0 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
240b0 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
240c0 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54  .** work with UT
240d0 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f  F-8, UTF-16le, o
240e0 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74  r UTF-16be.  But
240f0 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61   some implementa
24100 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20  tions may be.** 
24110 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77  more efficient w
24120 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67  ith one encoding
24130 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20   than another.  
24140 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  An application m
24150 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  ay.** invoke sql
24160 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
24170 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
24180 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
24190 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
241a0 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
241b0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
241c0 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
241d0 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
241e0 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75  tRep..** When mu
241f0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
24200 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
24210 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
24220 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
24230 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
24240 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
24250 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
24260 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
24270 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20  nversion..** If 
24280 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20  there is only a 
24290 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  single implement
242a0 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73  ation which does
242b0 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74   not care what t
242c0 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20  ext.** encoding 
242d0 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  is used, then th
242e0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
242f0 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c  t should be [SQL
24300 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20  ITE_ANY]..**.** 
24310 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
24320 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
24330 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
24340 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
24350 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
24360 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
24370 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
24380 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
24390 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
243a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e  .**.** The seven
243b0 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e  th, eighth and n
243c0 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  inth parameters,
243d0 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
243e0 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
243f0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
24400 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
24410 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
24420 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
24430 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
24440 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20  e. A scalar SQL 
24450 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
24460 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
24470 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
24480 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
24490 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y, NULL pointers
244a0 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
244b0 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
244c0 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
244d0 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72  ameters. An aggr
244e0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
244f0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
24500 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
24510 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
24520 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68  inal and NULL sh
24530 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66  ould be passed f
24540 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c  or xFunc. To del
24550 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
24560 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
24570 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
24580 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20  ss NULL for all 
24590 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 63  three function c
245a0 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
245b0 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
245c0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
245d0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
245e0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
245f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
24600 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
24610 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
24620 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
24630 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
24640 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
24650 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
24660 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 74  ncodings.  SQLit
24670 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
24680 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
24690 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
246a0 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
246b0 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
246c0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
246d0 69 73 20 75 73 65 64 2e 20 20 41 20 66 75 6e 63  is used.  A func
246e0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
246f0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
24700 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
24710 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
24720 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
24730 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
24740 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
24750 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
24760 72 67 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20  rg.  A function 
24770 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
24780 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
24790 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
247a0 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
247b0 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
247c0 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
247d0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
247e0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
247f0 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 41 20  fferent.  .** A 
24800 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
24810 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
24820 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
24830 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
24840 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
24850 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
24860 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
24870 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
24880 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
24890 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
248a0 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69  UTF16..**.** Bui
248b0 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
248c0 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
248d0 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
248e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
248f0 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 66  ctions..** The f
24900 69 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  irst application
24910 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
24920 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e  n with a given n
24930 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c  ame overrides al
24940 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75  l.** built-in fu
24950 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73  nctions in the s
24960 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
24970 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74  nnection] with t
24980 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a  he same name..**
24990 20 53 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c   Subsequent appl
249a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
249b0 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65  functions of the
249c0 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20   same name only 
249d0 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69  override .** pri
249e0 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  or application-d
249f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
24a00 20 74 68 61 74 20 61 72 65 20 61 6e 20 65 78 61   that are an exa
24a10 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65  ct match for the
24a20 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  .** number of pa
24a30 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65  rameters and pre
24a40 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e  ferred encoding.
24a50 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c 69 63  .**.** An applic
24a60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
24a70 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
24a80 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
24a90 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
24aa0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
24ab0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
24ac0 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
24ad0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24ae0 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
24af0 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
24b00 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
24b10 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
24b20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
24b30 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52  running..**.** R
24b40 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
24b50 5b 48 31 36 31 30 33 5d 20 5b 48 31 36 31 30 36  [H16103] [H16106
24b60 5d 20 5b 48 31 36 31 30 39 5d 20 5b 48 31 36 31  ] [H16109] [H161
24b70 31 32 5d 20 5b 48 31 36 31 31 38 5d 20 5b 48 31  12] [H16118] [H1
24b80 36 31 32 31 5d 20 5b 48 31 36 31 32 37 5d 0a 2a  6121] [H16127].*
24b90 2a 20 5b 48 31 36 31 33 30 5d 20 5b 48 31 36 31  * [H16130] [H161
24ba0 33 33 5d 20 5b 48 31 36 31 33 36 5d 20 5b 48 31  33] [H16136] [H1
24bb0 36 31 33 39 5d 20 5b 48 31 36 31 34 32 5d 0a 2a  6139] [H16142].*
24bc0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
24bd0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
24be0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
24bf0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
24c00 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
24c10 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
24c20 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
24c30 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
24c40 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
24c50 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
24c60 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
24c70 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
24c80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
24c90 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
24ca0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
24cb0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
24cc0 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
24cd0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
24ce0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
24cf0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
24d00 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
24d10 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
24d20 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
24d30 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
24d40 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
24d50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
24d60 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
24d70 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
24d80 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
24d90 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
24da0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
24db0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
24dc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
24dd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24de0 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
24df0 73 20 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 32  s {H10267} <S502
24e00 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a  00> <H16100>.**.
24e10 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
24e20 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
24e30 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
24e40 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
24e50 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
24e60 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
24e70 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
24e80 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
24e90 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
24ea0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
24eb0 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
24ec0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
24ed0 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
24ee0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
24ef0 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
24f00 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
24f10 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
24f20 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
24f30 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
24f40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
24f50 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
24f60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24f70 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
24f80 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
24f90 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
24fa0 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
24fb0 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
24fc0 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
24fd0 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
24fe0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
24ff0 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
25000 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
25010 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
25020 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
25030 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
25040 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
25050 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
25060 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
25070 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
25080 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
25090 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
250a0 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
250b0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
250c0 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
250d0 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
250e0 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
250f0 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
25100 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
25110 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
25120 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
25130 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
25140 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
25150 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
25160 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
25170 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
25180 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
25190 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
251a0 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
251b0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
251c0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
251d0 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
251e0 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
251f0 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
25200 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
25210 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
25220 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
25230 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
25240 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
25250 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
25260 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
25270 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
25280 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
25290 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
252a0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
252b0 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
252c0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
252d0 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
252e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
252f0 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
25300 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
25310 61 6c 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c  alues {H15100} <
25320 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
25330 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
25340 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
25350 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
25360 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
25370 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
25380 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
25390 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
253a0 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
253b0 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
253c0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
253d0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
253e0 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
253f0 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
25400 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
25410 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
25420 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
25430 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
25440 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
25450 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
25460 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
25470 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
25480 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
25490 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
254a0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34  egates..** The 4
254b0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
254c0 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
254d0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
254e0 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
254f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
25500 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
25510 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
25520 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
25530 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
25540 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
25550 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
25560 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
25570 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
25580 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
25590 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
255a0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
255b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
255c0 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
255d0 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
255e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
255f0 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
25600 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
25610 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
25620 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
25630 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
25640 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
25650 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
25660 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  havior..**.** Th
25670 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
25680 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
25690 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
256a0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
256b0 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
256c0 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
256d0 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
256e0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
256f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
25700 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
25710 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
25720 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
25730 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
25740 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
25750 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
25760 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
25770 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
25780 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
25790 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
257a0 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
257b0 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
257c0 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a  machine.  The.**
257d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
257e0 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
257f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
25800 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
25810 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
25820 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
25830 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
25840 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
25850 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
25860 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
25870 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
25880 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
25890 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
258a0 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
258b0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
258c0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
258d0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
258e0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
258f0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
25900 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
25910 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
25920 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
25930 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
25940 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
25950 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
25960 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
25970 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
25980 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
25990 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
259a0 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
259b0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
259c0 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
259d0 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
259e0 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
259f0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
25a00 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
25a10 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
25a20 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
25a30 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
25a40 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
25a50 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
25a60 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
25a70 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
25a80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
25a90 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
25aa0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
25ab0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
25ac0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
25ad0 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
25ae0 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
25af0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
25b00 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
25b10 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
25b20 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
25b30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
25b40 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
25b50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
25b60 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
25b70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
25b80 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
25b90 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
25ba0 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
25bb0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
25bc0 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
25bd0 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
25be0 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  eters..**.** Req
25bf0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
25c00 31 35 31 30 33 5d 20 5b 48 31 35 31 30 36 5d 20  15103] [H15106] 
25c10 5b 48 31 35 31 30 39 5d 20 5b 48 31 35 31 31 32  [H15109] [H15112
25c20 5d 20 5b 48 31 35 31 31 35 5d 20 5b 48 31 35 31  ] [H15115] [H151
25c30 31 38 5d 20 5b 48 31 35 31 32 31 5d 20 5b 48 31  18] [H15121] [H1
25c40 35 31 32 34 5d 0a 2a 2a 20 5b 48 31 35 31 32 37  5124].** [H15127
25c50 5d 20 5b 48 31 35 31 33 30 5d 20 5b 48 31 35 31  ] [H15130] [H151
25c60 33 33 5d 20 5b 48 31 35 31 33 36 5d 0a 2a 2f 0a  33] [H15136].*/.
25c70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
25c80 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
25c90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
25ca0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
25cb0 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
25cc0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
25cd0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
25ce0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
25cf0 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
25d00 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
25d10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
25d20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
25d30 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
25d40 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
25d50 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
25d60 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
25d70 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
25d80 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
25d90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
25da0 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
25db0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
25dc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
25dd0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
25de0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
25df0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
25e00 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
25e10 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
25e20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
25e30 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
25e40 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
25e50 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
25e60 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
25e70 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
25e80 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
25e90 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
25ea0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
25eb0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
25ec0 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
25ed0 20 43 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 30   Context {H16210
25ee0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20200>.**.**
25ef0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
25f00 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65  ion of aggregate
25f10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
25f20 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
25f30 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61  to allocate.** a
25f40 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73   structure for s
25f50 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
25f60 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  te..**.** The fi
25f70 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
25f80 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
25f90 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65  ontext() routine
25fa0 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61   is called for a
25fb0 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 61  .** particular a
25fc0 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65  ggregate, SQLite
25fd0 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65   allocates nByte
25fe0 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  s of memory, zer
25ff0 6f 65 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20  oes out that.** 
26000 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
26010 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
26020 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61   it. On second a
26030 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
26040 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
26050 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
26060 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
26070 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
26080 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20  ction index,.** 
26090 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
260a0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65  is returned. The
260b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
260c0 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
260d0 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20   can use.** the 
260e0 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20  returned buffer 
260f0 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61  to accumulate da
26100 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ta..**.** SQLite
26110 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
26120 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74  rees the allocat
26130 65 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74  ed buffer when t
26140 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
26150 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
26160 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
26170 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
26180 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  d be a copy of t
26190 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
261a0 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
261b0 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
261c0 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
261d0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
261e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f   the callback ro
261f0 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
26200 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
26210 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ate function..**
26220 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
26230 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
26240 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
26250 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
26260 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
26270 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
26280 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65  unning..**.** Re
26290 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
262a0 48 31 36 32 31 31 5d 20 5b 48 31 36 32 31 33 5d  H16211] [H16213]
262b0 20 5b 48 31 36 32 31 35 5d 20 5b 48 31 36 32 31   [H16215] [H1621
262c0 37 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  7].*/.void *sqli
262d0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
262e0 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
262f0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
26300 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
26310 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
26320 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48  For Functions {H
26330 31 36 32 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a  16240} <S20200>.
26340 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
26350 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
26360 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
26370 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
26380 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
26390 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
263a0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
263b0 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
263c0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
263d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
263e0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
263f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26400 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
26410 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
26420 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
26430 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
26440 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
26450 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
26460 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
26470 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
26480 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
26490 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
264a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
264b0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
264c0 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65  unning..**.** Re
264d0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
264e0 48 31 36 32 34 33 5d 0a 2a 2f 0a 76 6f 69 64 20  H16243].*/.void 
264f0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
26500 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
26510 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
26520 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
26530 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
26540 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 30  unctions {H16250
26550 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 30  } <S60600><S2020
26560 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
26570 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
26580 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
26590 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
265a0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
265b0 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
265c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
265d0 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
265e0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
265f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
26600 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
26610 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
26620 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
26630 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
26640 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
26650 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
26660 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
26670 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52  unction..**.** R
26680 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
26690 5b 48 31 36 32 35 33 5d 0a 2a 2f 0a 73 71 6c 69  [H16253].*/.sqli
266a0 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
266b0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
266c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
266d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
266e0 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
266f0 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31 36 32  liary Data {H162
26700 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  70} <S20200>.**.
26710 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
26720 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
26730 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
26740 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
26750 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
26760 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
26770 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
26780 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
26790 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
267a0 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
267b0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
267c0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
267d0 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
267e0 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
267f0 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
26800 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
26810 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
26820 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
26830 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
26840 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
26850 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
26860 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
26870 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
26880 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
26890 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
268a0 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
268b0 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
268c0 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
268d0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
268e0 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
268f0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
26900 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
26910 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
26920 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
26930 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
26940 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
26950 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
26960 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
26970 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
26980 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
26990 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
269a0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
269b0 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
269c0 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
269d0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
269e0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
269f0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
26a00 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
26a10 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
26a20 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
26a30 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
26a40 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
26a50 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
26a60 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
26a70 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
26a80 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
26a90 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f   function. If no
26aa0 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
26ab0 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20  en ever.** been 
26ac0 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20  set for the Nth 
26ad0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
26ae0 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
26af0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
26b00 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  g.** function pa
26b10 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e  rameter has chan
26b20 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
26b30 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
26b40 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
26b50 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72  _get_auxdata() r
26b60 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
26b70 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
26b80 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
26b90 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
26ba0 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64   saves the metad
26bb0 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
26bc0 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
26bd0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
26be0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
26bf0 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
26c00 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
26c10 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
26c20 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
26c30 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
26c40 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
26c50 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
26c60 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
26c70 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
26c80 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49   destroyed..** I
26c90 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
26ca0 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  , SQLite will in
26cb0 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
26cc0 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  tor.** function 
26cd0 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68  given by the 4th
26ce0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
26cf0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
26d00 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65  a() on.** the me
26d10 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20  tadata when the 
26d20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
26d30 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
26d40 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77   changes.** or w
26d50 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
26d60 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c  ement completes,
26d70 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
26d80 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51   first..**.** SQ
26d90 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
26da0 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63  call the destruc
26db0 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74  tor and drop met
26dc0 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20  adata on any.** 
26dd0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79  parameter of any
26de0 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79   function at any
26df0 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79   time.  The only
26e00 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68   guarantee is th
26e10 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75  at.** the destru
26e20 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c  ctor will be cal
26e30 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d  led before the m
26e40 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70  etadata is dropp
26e50 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61  ed..**.** In pra
26e60 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
26e70 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
26e80 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
26e90 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65  lls for.** expre
26ea0 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ssions that are 
26eb0 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70  constant at comp
26ec0 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69  ile time. This i
26ed0 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a  ncludes literal.
26ee0 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51  ** values and SQ
26ef0 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a  L variables..**.
26f00 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
26f10 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
26f20 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
26f30 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
26f40 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
26f50 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
26f60 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
26f70 73 3a 0a 2a 2a 20 5b 48 31 36 32 37 32 5d 20 5b  s:.** [H16272] [
26f80 48 31 36 32 37 34 5d 20 5b 48 31 36 32 37 36 5d  H16274] [H16276]
26f90 20 5b 48 31 36 32 37 37 5d 20 5b 48 31 36 32 37   [H16277] [H1627
26fa0 38 5d 20 5b 48 31 36 32 37 39 5d 0a 2a 2f 0a 76  8] [H16279].*/.v
26fb0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
26fc0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
26fd0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
26fe0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
26ff0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
27000 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
27010 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
27020 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
27030 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27040 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
27050 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
27060 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b  uctor Behavior {
27070 48 31 30 32 38 30 7d 20 3c 53 33 30 31 30 30 3e  H10280} <S30100>
27080 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
27090 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20   special values 
270a0 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
270b0 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
270c0 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
270d0 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
270e0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
270f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
27100 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20  lob()].  If the 
27110 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
27120 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
27130 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
27140 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
27150 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
27160 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
27170 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
27180 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
27190 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
271a0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49  ed.  The.** SQLI
271b0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
271c0 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
271d0 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
271e0 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
271f0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
27200 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
27210 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
27220 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
27230 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
27240 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
27250 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
27260 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
27270 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
27280 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
27290 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
272a0 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
272b0 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
272c0 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
272d0 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
272e0 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
272f0 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
27300 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
27310 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
27320 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
27330 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
27340 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
27350 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
27360 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
27370 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
27380 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
27390 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30   Function {H1640
273a0 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a  0} <S20200>.**.*
273b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
273c0 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
273d0 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
273e0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
273f0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
27400 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
27410 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
27420 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
27430 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
27440 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
27450 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
27460 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
27470 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
27480 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
27490 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
274a0 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70  much like the [p
274b0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
274c0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66  ] family of.** f
274d0 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f  unctions used to
274e0 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
274f0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
27500 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
27510 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
27520 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72   to the [SQL par
27530 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74  ameter] document
27540 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
27550 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
27560 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
27570 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
27580 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
27590 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
275a0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
275b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
275c0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
275d0 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
275e0 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
275f0 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
27600 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
27610 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
27620 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
27630 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
27640 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  meter..**.** The
27650 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27660 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
27670 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
27680 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
27690 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
276a0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
276b0 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
276c0 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
276d0 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
276e0 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
276f0 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
27700 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
27710 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eter..**.** The 
27720 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
27730 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
27740 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
27750 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
27760 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
27770 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
27780 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
27790 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
277a0 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
277b0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
277c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
277d0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
277e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
277f0 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
27800 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
27810 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
27820 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
27830 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
27840 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
27850 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
27860 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
27870 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
27880 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
27890 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
278a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
278b0 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
278c0 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
278d0 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74  age.  SQLite int
278e0 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f  erprets the erro
278f0 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72  r.** message str
27900 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
27910 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
27920 61 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 65  as UTF-8. SQLite
27930 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
27940 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
27950 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
27960 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
27970 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
27980 79 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74  yte order.  If t
27990 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
279a0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
279b0 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
279c0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
279d0 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
279e0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
279f0 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65  ite takes as the
27a00 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
27a10 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68  e all text up th
27a20 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
27a30 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
27a40 2a 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 20  ** If the third 
27a50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
27a60 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
27a70 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
27a80 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
27a90 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
27aa0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
27ab0 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
27ac0 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
27ad0 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
27ae0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
27af0 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
27b00 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  sage..** The sql
27b10 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
27b20 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
27b30 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
27b40 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
27b50 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
27b60 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
27b70 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
27b80 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
27b90 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
27ba0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
27bb0 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
27bc0 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
27bd0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
27be0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
27bf0 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  rm..** The sqlit
27c00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
27c10 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
27c20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
27c30 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
27c40 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
27c50 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
27c60 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
27c70 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  on.  By default,
27c80 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f  .** the error co
27c90 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52  de is SQLITE_ERR
27ca0 4f 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e  OR.  A subsequen
27cb0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
27cc0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
27cd0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
27ce0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
27cf0 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  resets the error
27d00 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f   code to SQLITE_
27d10 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ERROR..**.** The
27d20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27d30 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61  toobig() interfa
27d40 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
27d50 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
27d60 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
27d70 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f   that a string o
27d80 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e  r BLOB is to lon
27d90 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a  g to represent..
27da0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27db0 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29  3_result_nomem()
27dc0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
27dd0 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
27de0 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
27df0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
27e00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
27e10 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
27e20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
27e30 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
27e40 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
27e50 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
27e60 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
27e70 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
27e80 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
27e90 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
27ea0 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
27eb0 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
27ec0 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  nt..** The sqlit
27ed0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
27ee0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
27ef0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
27f00 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
27f10 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
27f20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
27f30 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
27f40 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
27f50 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
27f60 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
27f70 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
27f80 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
27f90 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
27fa0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
27fb0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
27fc0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
27fd0 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
27fe0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27ff0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
28000 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28010 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
28020 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
28030 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
28040 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
28050 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
28060 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
28070 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
28080 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
28090 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
280a0 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
280b0 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
280c0 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
280d0 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
280e0 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
280f0 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
28100 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
28110 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
28120 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c  ectively..** SQL
28130 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
28140 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
28150 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
28160 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
28170 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
28180 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
28190 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
281a0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
281b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
281c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
281d0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
281e0 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
281f0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
28200 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
28210 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
28220 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
28230 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
28240 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20  haracter..** If 
28250 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
28260 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
28270 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
28280 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
28290 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
282a0 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
282b0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
282c0 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
282d0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
282e0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
282f0 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
28300 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
28310 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
28320 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74   result..** If t
28330 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
28340 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
28350 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
28360 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
28370 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
28380 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  b is a non-NULL 
28390 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
283a0 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a  Lite calls that.
283b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74  ** function as t
283c0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e  he destructor on
283d0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
283e0 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74  B result when it
283f0 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
28400 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
28410 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
28420 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
28430 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
28440 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
28450 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
28460 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
28470 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
28480 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
28490 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
284a0 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
284b0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
284c0 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
284d0 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
284e0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
284f0 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
28500 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
28510 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
28520 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
28530 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
28540 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
28550 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
28560 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20  ..** If the 4th 
28570 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
28580 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28590 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
285a0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
285b0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
285c0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
285d0 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
285e0 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
285f0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
28600 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
28610 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
28620 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
28630 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
28640 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
28650 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rns..**.** The s
28660 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
28670 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
28680 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
28690 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
286a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
286b0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
286c0 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
286d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
286e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
286f0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
28700 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
28710 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  he.** sqlite3_re
28720 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
28730 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
28740 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
28750 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f  te3_value].** so
28760 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
28770 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66  e3_value] specif
28780 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d  ied in the param
28790 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20  eter may change 
287a0 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63  or.** be dealloc
287b0 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ated after sqlit
287c0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
287d0 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75  ) returns withou
287e0 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72  t harm..** A [pr
287f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28800 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
28810 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
28820 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
28830 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28840 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
28850 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
28860 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
28870 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
28880 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
28890 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
288a0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
288b0 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
288c0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
288d0 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
288e0 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
288f0 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
28900 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
28910 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28920 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
28930 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
28940 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
28950 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
28960 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
28970 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ned..**.** Requi
28980 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36  rements:.** [H16
28990 34 30 33 5d 20 5b 48 31 36 34 30 36 5d 20 5b 48  403] [H16406] [H
289a0 31 36 34 30 39 5d 20 5b 48 31 36 34 31 32 5d 20  16409] [H16412] 
289b0 5b 48 31 36 34 31 35 5d 20 5b 48 31 36 34 31 38  [H16415] [H16418
289c0 5d 20 5b 48 31 36 34 32 31 5d 20 5b 48 31 36 34  ] [H16421] [H164
289d0 32 34 5d 0a 2a 2a 20 5b 48 31 36 34 32 37 5d 20  24].** [H16427] 
289e0 5b 48 31 36 34 33 30 5d 20 5b 48 31 36 34 33 33  [H16430] [H16433
289f0 5d 20 5b 48 31 36 34 33 36 5d 20 5b 48 31 36 34  ] [H16436] [H164
28a00 33 39 5d 20 5b 48 31 36 34 34 32 5d 20 5b 48 31  39] [H16442] [H1
28a10 36 34 34 35 5d 20 5b 48 31 36 34 34 38 5d 0a 2a  6445] [H16448].*
28a20 2a 20 5b 48 31 36 34 35 31 5d 20 5b 48 31 36 34  * [H16451] [H164
28a30 35 34 5d 20 5b 48 31 36 34 35 37 5d 20 5b 48 31  54] [H16457] [H1
28a40 36 34 36 30 5d 20 5b 48 31 36 34 36 33 5d 0a 2a  6460] [H16463].*
28a50 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
28a60 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
28a70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
28a80 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
28a90 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
28aa0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
28ab0 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
28ac0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
28ad0 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
28ae0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
28af0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
28b00 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
28b10 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
28b20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
28b30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28b40 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
28b50 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
28b60 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
28b70 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
28b80 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
28b90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
28ba0 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
28bb0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
28bc0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
28bd0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
28be0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
28bf0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
28c00 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
28c10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
28c20 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
28c30 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
28c40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
28c50 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
28c60 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
28c70 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
28c80 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
28c90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28ca0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
28cb0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
28cc0 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
28cd0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
28ce0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
28cf0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
28d00 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
28d10 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
28d20 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
28d30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
28d40 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
28d50 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
28d60 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
28d70 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
28d80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
28d90 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
28da0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
28db0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
28dc0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
28dd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28de0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
28df0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
28e00 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
28e10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
28e20 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
28e30 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
28e40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28e50 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
28e60 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20  ating Sequences 
28e70 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33 30 30  {H16600} <S20300
28e80 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  >.**.** These fu
28e90 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64  nctions are used
28ea0 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c   to add new coll
28eb0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
28ec0 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  to the.** [datab
28ed0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
28ee0 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
28ef0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
28f00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
28f10 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61  of the new colla
28f20 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
28f30 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20   specified as a 
28f40 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
28f50 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
28f60 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
28f70 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
28f80 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
28f90 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
28fa0 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69   string for sqli
28fb0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
28fc0 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c  tion16(). In all
28fd0 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61   cases.** the na
28fe0 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20  me is passed as 
28ff0 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
29000 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
29010 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72  .** The third ar
29020 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e  gument may be on
29030 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
29040 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ts [SQLITE_UTF8]
29050 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  ,.** [SQLITE_UTF
29060 31 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16LE], or [SQLIT
29070 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69  E_UTF16BE], indi
29080 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20  cating that the 
29090 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  user-supplied.**
290a0 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
290b0 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f   to be passed po
290c0 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
290d0 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  s encoded using 
290e0 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36  UTF-8,.** UTF-16
290f0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20   little-endian, 
29100 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  or UTF-16 big-en
29110 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
29120 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ly. The.** third
29130 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20   argument might 
29140 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f  also be [SQLITE_
29150 55 54 46 31 36 5d 20 74 6f 20 69 6e 64 69 63 61  UTF16] to indica
29160 74 65 20 74 68 61 74 20 74 68 65 20 72 6f 75 74  te that the rout
29170 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74 73 20 70  ine.** expects p
29180 6f 69 6e 74 65 72 73 20 74 6f 20 62 65 20 55 54  ointers to be UT
29190 46 2d 31 36 20 73 74 72 69 6e 67 73 20 69 6e 20  F-16 strings in 
291a0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
291b0 6f 72 64 65 72 2c 20 6f 72 20 74 68 65 0a 2a 2a  order, or the.**
291c0 20 61 72 67 75 6d 65 6e 74 20 63 61 6e 20 62 65   argument can be
291d0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
291e0 4c 49 47 4e 45 44 5d 20 69 66 20 74 68 65 0a 2a  LIGNED] if the.*
291f0 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78  * the routine ex
29200 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
29210 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c  o 16-bit word al
29220 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  igned strings.**
29230 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68   of UTF-16 in th
29240 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
29250 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  der..**.** A poi
29260 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72  nter to the user
29270 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e   supplied routin
29280 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  e must be passed
29290 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a   as the fifth.**
292a0 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 69   argument.  If i
292b0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20  t is NULL, this 
292c0 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64  is the same as d
292d0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c  eleting the coll
292e0 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
292f0 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74  e (so that SQLit
29300 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74  e cannot call it
29310 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61   anymore)..** Ea
29320 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c  ch time the appl
29330 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64  ication supplied
29340 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
29350 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73  oked, it is pass
29360 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72  ed.** as its fir
29370 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20 63  st parameter a c
29380 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
29390 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
293a0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
293b0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  * to sqlite3_cre
293c0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
293d0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
293e0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
293f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  .**.** The remai
29400 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74  ning arguments t
29410 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
29420 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  n-supplied routi
29430 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e  ne are two strin
29440 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72  gs,.** each repr
29450 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65  esented by a (le
29460 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72  ngth, data) pair
29470 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20   and encoded in 
29480 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  the encoding.** 
29490 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20  that was passed 
294a0 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  as the third arg
294b0 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63  ument when the c
294c0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
294d0 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65  e was.** registe
294e0 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20  red. {END}  The 
294f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
29500 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f  ned collation ro
29510 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20  utine should.** 
29520 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c  return negative,
29530 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76   zero or positiv
29540 65 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  e if the first s
29550 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
29560 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c  an,.** equal to,
29570 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
29580 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69   the second stri
29590 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47  ng. i.e. (STRING
295a0 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a  1 - STRING2)..**
295b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
295c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
295d0 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
295e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
295f0 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65  collation().** e
29600 78 63 65 70 74 20 74 68 61 74 20 69 74 20 74 61  xcept that it ta
29610 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67  kes an extra arg
29620 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
29630 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a   destructor for.
29640 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  ** the collation
29650 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
29660 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e  r is called when
29670 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
29680 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61  s.** destroyed a
29690 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63  nd is passed a c
296a0 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74  opy of the fourt
296b0 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64  h parameter void
296c0 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20  * pointer.** of 
296d0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
296e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
296f0 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73  )..** Collations
29700 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77   are destroyed w
29710 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
29720 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
29730 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
29740 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
29750 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
29760 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62   when the [datab
29770 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
29780 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69  is closed.** usi
29790 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
297a0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  e()]..**.** See 
297b0 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f  also:  [sqlite3_
297c0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
297d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
297e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
297f0 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65  d16()]..**.** Re
29800 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
29810 48 31 36 36 30 33 5d 20 5b 48 31 36 36 30 34 5d  H16603] [H16604]
29820 20 5b 48 31 36 36 30 36 5d 20 5b 48 31 36 36 30   [H16606] [H1660
29830 39 5d 20 5b 48 31 36 36 31 32 5d 20 5b 48 31 36  9] [H16612] [H16
29840 36 31 35 5d 20 5b 48 31 36 36 31 38 5d 20 5b 48  615] [H16618] [H
29850 31 36 36 32 31 5d 0a 2a 2a 20 5b 48 31 36 36 32  16621].** [H1662
29860 34 5d 20 5b 48 31 36 36 32 37 5d 20 5b 48 31 36  4] [H16627] [H16
29870 36 33 30 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  630].*/.int sqli
29880 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
29890 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
298a0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
298b0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
298c0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
298d0 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
298e0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
298f0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
29900 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
29910 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
29920 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
29930 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
29940 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
29950 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
29960 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
29970 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
29980 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
29990 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
299a0 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
299b0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
299c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
299d0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
299e0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
299f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
29a00 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
29a10 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
29a20 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
29a30 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
29a40 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
29a50 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
29a60 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
29a70 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
29a80 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c 53 32  cks {H16700} <S2
29a90 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  0300>.**.** To a
29aa0 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
29ab0 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
29ac0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
29ad0 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
29ae0 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
29af0 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
29b00 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
29b10 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
29b20 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
29b30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
29b40 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68   to be called wh
29b50 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
29b60 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
29b70 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
29b80 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  uired..**.** If 
29b90 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
29ba0 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
29bb0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
29bc0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
29bd0 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
29be0 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
29bf0 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
29c00 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
29c10 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
29c20 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
29c30 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20 49 66  F-8. {H16703} If
29c40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
29c50 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
29c60 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
29c70 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
29c80 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
29c90 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
29ca0 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c  order..** A call
29cb0 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
29cc0 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79  ion replaces any
29cd0 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61   existing callba
29ce0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ck..**.** When t
29cf0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
29d00 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
29d10 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
29d20 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
29d30 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
29d40 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
29d50 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
29d60 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
29d70 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
29d80 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
29d90 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
29da0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
29db0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
29dc0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
29dd0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
29de0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
29df0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
29e00 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
29e10 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
29e20 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
29e30 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
29e40 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
29e50 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
29e60 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
29e70 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
29e80 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
29e90 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
29ea0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a  tion sequence..*
29eb0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
29ec0 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
29ed0 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
29ee0 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
29ef0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
29f00 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
29f10 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
29f20 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
29f30 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
29f40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
29f50 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
29f60 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
29f70 73 3a 0a 2a 2a 20 5b 48 31 36 37 30 32 5d 20 5b  s:.** [H16702] [
29f80 48 31 36 37 30 34 5d 20 5b 48 31 36 37 30 36 5d  H16704] [H16706]
29f90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29fa0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
29fb0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
29fc0 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
29fd0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
29fe0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
29ff0 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
2a000 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
2a010 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
2a020 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2a030 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
2a040 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
2a050 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
2a060 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
2a070 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
2a080 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
2a090 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
2a0a0 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
2a0b0 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
2a0c0 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
2a0d0 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
2a0e0 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
2a0f0 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
2a100 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
2a110 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
2a120 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
2a130 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
2a140 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
2a150 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2a160 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2a170 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
2a180 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
2a190 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
2a1a0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
2a1b0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
2a1c0 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
2a1d0 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
2a1e0 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
2a1f0 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
2a200 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
2a210 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
2a220 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
2a230 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
2a240 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
2a250 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
2a260 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
2a270 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
2a280 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
2a290 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
2a2a0 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
2a2b0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
2a2c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
2a2d0 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  ekey(.  sqlite3 
2a2e0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2a2f0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2a300 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
2a310 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2a320 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
2a330 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
2a340 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
2a350 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65   CAPI3REF: Suspe
2a360 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72  nd Execution For
2a370 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 48   A Short Time {H
2a380 31 30 35 33 30 7d 20 3c 53 34 30 34 31 30 3e 0a  10530} <S40410>.
2a390 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2a3a0 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69  3_sleep() functi
2a3b0 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75  on causes the cu
2a3c0 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20  rrent thread to 
2a3d0 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f  suspend executio
2a3e0 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73  n.** for at leas
2a3f0 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  t a number of mi
2a400 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69  lliseconds speci
2a410 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61  fied in its para
2a420 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
2a430 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
2a440 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75  stem does not su
2a450 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75  pport sleep requ
2a460 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c  ests with.** mil
2a470 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65  lisecond time re
2a480 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74  solution, then t
2a490 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20  he time will be 
2a4a0 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a  rounded up to.**
2a4b0 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63   the nearest sec
2a4c0 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20  ond. The number 
2a4d0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
2a4e0 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c  of sleep actuall
2a4f0 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66  y.** requested f
2a500 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e  rom the operatin
2a510 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75  g system is retu
2a520 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rned..**.** SQLi
2a530 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
2a540 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
2a550 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
2a560 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
2a570 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
2a580 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
2a590 63 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ct..**.** Requir
2a5a0 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 33 33 5d  ements: [H10533]
2a5b0 20 5b 48 31 30 35 33 36 5d 0a 2a 2f 0a 69 6e 74   [H10536].*/.int
2a5c0 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
2a5d0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2a5e0 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
2a5f0 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
2a600 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
2a610 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30 30 30   {H10310} <S2000
2a620 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73  0>.**.** If this
2a630 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
2a640 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
2a650 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
2a660 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
2a670 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
2a680 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
2a690 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
2a6a0 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
2a6b0 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
2a6c0 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20   will be placed 
2a6d0 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  in that director
2a6e0 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 72 69  y.  If this vari
2a6f0 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  able.** is a NUL
2a700 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
2a710 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20  SQLite performs 
2a720 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
2a730 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74  appropriate.** t
2a740 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69  emporary file di
2a750 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
2a760 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
2a770 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
2a780 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
2a790 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
2a7a0 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
2a7b0 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
2a7c0 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
2a7d0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
2a7e0 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
2a7f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2a800 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
2a810 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2a820 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
2a830 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
2a840 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
2a850 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
2a860 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
2a870 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
2a880 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
2a890 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
2a8a0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
2a8b0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
2a8c0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
2a8d0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
2a8e0 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
2a8f0 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
2a900 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 74  er..**.** The [t
2a910 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
2a920 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
2a930 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
2a940 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
2a950 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
2a960 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
2a970 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2a980 61 6c 6c 6f 63 5d 2e 20 20 46 75 72 74 68 65 72  alloc].  Further
2a990 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65  more,.** the [te
2a9a0 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
2a9b0 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79  ry pragma] alway
2a9c0 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  s assumes that a
2a9d0 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61  ny string.** tha
2a9e0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
2a9f0 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c  points to is hel
2aa00 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61  d in memory obta
2aa10 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
2aa20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61  qlite3_malloc] a
2aa30 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61  nd the pragma ma
2aa40 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65  y attempt to fre
2aa50 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a  e that memory.**
2aa60 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2aa70 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c  free]..** Hence,
2aa80 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   if this variabl
2aa90 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69  e is modified di
2aaa0 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69  rectly, either i
2aab0 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d  t should be.** m
2aac0 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65  ade NULL or made
2aad0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
2aae0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
2aaf0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2ab00 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68  c].** or else th
2ab10 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65  e use of the [te
2ab20 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
2ab30 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c  ry pragma] shoul
2ab40 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f  d be avoided..*/
2ab50 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
2ab60 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
2ab70 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
2ab80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
2ab90 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d  st For Auto-Comm
2aba0 69 74 20 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d  it Mode {H12930}
2abb0 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59   <S60200>.** KEY
2abc0 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
2abd0 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54  it mode}.**.** T
2abe0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
2abf0 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65  utocommit() inte
2ac00 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
2ac10 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
2ac20 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
2ac30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ac40 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
2ac50 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
2ac60 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
2ac70 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74  ely.  Autocommit
2ac80 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64   mode is on by d
2ac90 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63  efault..** Autoc
2aca0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69  ommit mode is di
2acb0 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47  sabled by a [BEG
2acc0 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  IN] statement..*
2acd0 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  * Autocommit mod
2ace0 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20  e is re-enabled 
2acf0 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
2ad00 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
2ad10 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
2ad20 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
2ad30 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
2ad40 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
2ad50 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
2ad60 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f  ransaction (erro
2ad70 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51  rs including [SQ
2ad80 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_FULL], [SQL
2ad90 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b  ITE_IOERR],.** [
2ada0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b  SQLITE_NOMEM], [
2adb0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e  SQLITE_BUSY], an
2adc0 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  d [SQLITE_INTERR
2add0 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a  UPT]) then the.*
2ade0 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69  * transaction mi
2adf0 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ght be rolled ba
2ae00 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
2ae10 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20  .  The only way 
2ae20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77  to.** find out w
2ae30 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75  hether SQLite au
2ae40 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
2ae50 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ed back the tran
2ae60 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a  saction after.**
2ae70 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20   an error is to 
2ae80 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f  use this functio
2ae90 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  n..**.** If anot
2aea0 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
2aeb0 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
2aec0 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
2aed0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2aee0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
2aef0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
2af00 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
2af10 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69  eturn value.** i
2af20 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2af30 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
2af40 20 5b 48 31 32 39 33 31 5d 20 5b 48 31 32 39 33   [H12931] [H1293
2af50 32 5d 20 5b 48 31 32 39 33 33 5d 20 5b 48 31 32  2] [H12933] [H12
2af60 39 33 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  934].*/.int sqli
2af70 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
2af80 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  it(sqlite3*);../
2af90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2afa0 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65  ind The Database
2afb0 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65   Handle Of A Pre
2afc0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2afd0 7b 48 31 33 31 32 30 7d 20 3c 53 36 30 36 30 30  {H13120} <S60600
2afe0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
2aff0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
2b000 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b010 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2b020 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
2b030 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
2b040 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b050 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 54 68  nt] belongs.  Th
2b060 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2b070 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72  ection].** retur
2b080 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64  ned by sqlite3_d
2b090 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20  b_handle is the 
2b0a0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
2b0b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
2b0c0 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72  was the first ar
2b0d0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
2b0e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b0f0 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72  e_v2()] call (or
2b100 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74   its variants) t
2b110 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a  hat was used to.
2b120 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74  ** create the st
2b130 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66  atement in the f
2b140 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a  irst place..**.*
2b150 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
2b160 5b 48 31 33 31 32 33 5d 0a 2a 2f 0a 73 71 6c 69  [H13123].*/.sqli
2b170 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
2b180 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
2b190 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2b1a0 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65  PI3REF: Find the
2b1b0 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73   next prepared s
2b1c0 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 34 30  tatement {H13140
2b1d0 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60600>.**.**
2b1e0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
2b1f0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2b200 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70  r to the next [p
2b210 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b220 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d  t] after.** pStm
2b230 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
2b240 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
2b250 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e  connection] pDb.
2b260 20 20 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55    If pStmt is NU
2b270 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  LL.** then this 
2b280 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b290 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2b2a0 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65  he first prepare
2b2b0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61  d statement.** a
2b2c0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
2b2d0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2b2e0 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 49 66 20  ection pDb.  If 
2b2f0 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74  no prepared stat
2b300 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69  ement.** satisfi
2b310 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e  es the condition
2b320 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
2b330 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  e, it returns NU
2b340 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64  LL..**.** The [d
2b350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b360 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e  on] pointer D in
2b370 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
2b380 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
2b390 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65  (D,S)] must refe
2b3a0 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74  r to an open dat
2b3b0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2b3c0 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69  ion and in parti
2b3d0 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62  cular must not b
2b3e0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
2b3f0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
2b400 65 6e 74 73 3a 20 5b 48 31 33 31 34 33 5d 20 5b  ents: [H13143] [
2b410 48 31 33 31 34 36 5d 20 5b 48 31 33 31 34 39 5d  H13146] [H13149]
2b420 20 5b 48 31 33 31 35 32 5d 0a 2a 2f 0a 73 71 6c   [H13152].*/.sql
2b430 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74  ite3_stmt *sqlit
2b440 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c  e3_next_stmt(sql
2b450 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74  ite3 *pDb, sqlit
2b460 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2b470 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b480 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c  : Commit And Rol
2b490 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69  lback Notificati
2b4a0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31  on Callbacks {H1
2b4b0 32 39 35 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2950} <S60400>.*
2b4c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2b4d0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69  _commit_hook() i
2b4e0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2b4f0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
2b500 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2b510 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
2b520 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
2b530 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d  s [COMMIT | comm
2b540 69 74 74 65 64 5d 2e 0a 2a 2a 20 41 6e 79 20 63  itted]..** Any c
2b550 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
2b560 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2b570 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
2b580 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
2b590 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2b5a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2b5b0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68  verridden..** Th
2b5c0 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  e sqlite3_rollba
2b5d0 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  ck_hook() interf
2b5e0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
2b5f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
2b600 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
2b610 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
2b620 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f  ansaction is [RO
2b630 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20  LLBACK | rolled 
2b640 62 61 63 6b 5d 2e 0a 2a 2a 20 41 6e 79 20 63 61  back]..** Any ca
2b650 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
2b660 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2b670 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
2b680 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
2b690 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2b6a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
2b6b0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65  erridden..** The
2b6c0 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69   pArg argument i
2b6d0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
2b6e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2b6f0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
2b700 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74  back on a commit
2b710 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72   hook function r
2b720 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
2b730 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d  .** then the com
2b740 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64  mit is converted
2b750 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b   into a rollback
2b760 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
2b770 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  er function was 
2b780 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
2b790 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41  tered, its.** pA
2b7a0 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  rg value is retu
2b7b0 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
2b7c0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
2b7d0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  d..**.** The cal
2b7e0 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61  lback implementa
2b7f0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f  tion must not do
2b800 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
2b810 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
2b820 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2b830 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
2b840 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  ed the callback.
2b850 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a    Any actions.**
2b860 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64   to modify the d
2b870 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b880 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72  on must be defer
2b890 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20  red until after 
2b8a0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f  the.** completio
2b8b0 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
2b8c0 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74  3_step()] call t
2b8d0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
2b8e0 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72  e commit.** or r
2b8f0 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20  ollback hook in 
2b900 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
2b910 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
2b920 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b930 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
2b940 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
2b950 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
2b960 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b970 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
2b980 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
2b990 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
2b9a0 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  h..**.** Registe
2b9b0 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63  ring a NULL func
2b9c0 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68  tion disables th
2b9d0 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
2b9e0 2a 20 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69  * When the commi
2b9f0 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  t hook callback 
2ba00 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2ba10 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49  zero, the [COMMI
2ba20 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  T].** operation 
2ba30 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f  is allowed to co
2ba40 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e  ntinue normally.
2ba50 20 20 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20    If the commit 
2ba60 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20  hook.** returns 
2ba70 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
2ba80 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63  he [COMMIT] is c
2ba90 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
2baa0 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 54  [ROLLBACK]..** T
2bab0 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  he rollback hook
2bac0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61   is invoked on a
2bad0 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72   rollback that r
2bae0 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f  esults from a co
2baf0 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74  mmit.** hook ret
2bb00 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c  urning non-zero,
2bb10 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c   just as it woul
2bb20 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74  d be with any ot
2bb30 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  her rollback..**
2bb40 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70  .** For the purp
2bb50 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
2bb60 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
2bb70 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
2bb80 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  been.** rolled b
2bb90 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
2bba0 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
2bbb0 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
2bbc0 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
2bbd0 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
2bbe0 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
2bbf0 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
2bc00 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72   occur..** The r
2bc10 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
2bc20 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2bc30 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
2bc40 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
2bc50 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2bc60 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74   because the dat
2bc70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2bc80 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54   is closed..** T
2bc90 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
2bca0 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
2bcb0 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
2bcc0 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65  tion is.** rolle
2bcd0 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 61  d back because a
2bce0 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b   commit callback
2bcf0 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65   returned non-ze
2bd00 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68  ro..** <todo> Ch
2bd10 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f  eck on this </to
2bd20 64 6f 3e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  do>.**.** See al
2bd30 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
2bd40 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69  update_hook()] i
2bd50 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2bd60 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
2bd70 20 5b 48 31 32 39 35 31 5d 20 5b 48 31 32 39 35   [H12951] [H1295
2bd80 32 5d 20 5b 48 31 32 39 35 33 5d 20 5b 48 31 32  2] [H12953] [H12
2bd90 39 35 34 5d 20 5b 48 31 32 39 35 35 5d 0a 2a 2a  954] [H12955].**
2bda0 20 5b 48 31 32 39 36 31 5d 20 5b 48 31 32 39 36   [H12961] [H1296
2bdb0 32 5d 20 5b 48 31 32 39 36 33 5d 20 5b 48 31 32  2] [H12963] [H12
2bdc0 39 36 34 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  964].*/.void *sq
2bdd0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2bde0 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
2bdf0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
2be00 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
2be10 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
2be20 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
2be30 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
2be40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2be50 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
2be60 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
2be70 62 61 63 6b 73 20 7b 48 31 32 39 37 30 7d 20 3c  backs {H12970} <
2be80 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60400>.**.** Th
2be90 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
2bea0 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
2beb0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
2bec0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
2bed0 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
2bee0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2bef0 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  ] identified by 
2bf00 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2bf10 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  nt.** to be invo
2bf20 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72  ked whenever a r
2bf30 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
2bf40 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
2bf50 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62  ed..** Any callb
2bf60 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2bf70 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
2bf80 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
2bf90 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2bfa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2bfb0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2bfc0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
2bfd0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
2bfe0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e  inter to the fun
2bff0 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20  ction to invoke 
2c000 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73  when a.** row is
2c010 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
2c020 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
2c030 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
2c040 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c  ment to the call
2c050 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
2c060 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
2c070 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
2c080 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
2c090 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
2c0a0 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  callback argumen
2c0b0 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
2c0c0 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51  ITE_INSERT], [SQ
2c0d0 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a  LITE_DELETE],.**
2c0e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41   or [SQLITE_UPDA
2c0f0 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  TE], depending o
2c100 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  n the operation 
2c110 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20  that caused the 
2c120 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62  callback.** to b
2c130 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68  e invoked..** Th
2c140 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
2c150 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  th arguments to 
2c160 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  the callback con
2c170 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f  tain pointers to
2c180 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2c190 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20   and table name 
2c1a0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
2c1b0 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20  ffected row..** 
2c1c0 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61  The final callba
2c1d0 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
2c1e0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
2c1f0 68 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68  he row..** In th
2c200 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64  e case of an upd
2c210 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65  ate, this is the
2c220 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74   [rowid] after t
2c230 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20  he update takes 
2c240 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  place..**.** The
2c250 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20   update hook is 
2c260 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
2c270 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
2c280 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d   tables are.** m
2c290 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71  odified (i.e. sq
2c2a0 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
2c2b0 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29  sqlite_sequence)
2c2c0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 63  ..**.** In the c
2c2d0 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
2c2e0 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74  ation, the updat
2c2f0 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74  e hook.** is not
2c300 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75   invoked when du
2c310 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61  plication rows a
2c320 72 65 20 64 65 6c 65 74 65 64 20 62 65 63 61 75  re deleted becau
2c330 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20  se of an.** [ON 
2c340 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f  CONFLICT | ON CO
2c350 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20  NFLICT REPLACE] 
2c360 63 6c 61 75 73 65 2e 20 20 4e 6f 72 20 69 73 20  clause.  Nor is 
2c370 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
2c380 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ** invoked when 
2c390 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
2c3a0 20 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e   using the [trun
2c3b0 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
2c3c0 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70  n]..** The excep
2c3d0 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e  tions defined in
2c3e0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 20   this paragraph 
2c3f0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
2c400 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65  a future.** rele
2c410 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
2c420 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20  *.** The update 
2c430 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74  hook implementat
2c440 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ion must not do 
2c450 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
2c460 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
2c470 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2c480 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
2c490 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  d the update hoo
2c4a0 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a  k.  Any actions.
2c4b0 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ** to modify the
2c4c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2c4d0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66  tion must be def
2c4e0 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65  erred until afte
2c4f0 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  r the.** complet
2c500 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
2c510 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2c520 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
2c530 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e  the update hook.
2c540 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
2c550 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c560 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
2c570 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
2c580 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
2c590 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2c5a0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
2c5b0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
2c5c0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
2c5d0 68 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  h..**.** If anot
2c5e0 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73  her function was
2c5f0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
2c600 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67  stered, its pArg
2c610 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74   value.** is ret
2c620 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
2c630 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  e NULL is return
2c640 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ed..**.** See al
2c650 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
2c660 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61  commit_hook()] a
2c670 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  nd [sqlite3_roll
2c680 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20  back_hook()].** 
2c690 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a  interfaces..**.*
2c6a0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
2c6b0 2a 2a 20 5b 48 31 32 39 37 31 5d 20 5b 48 31 32  ** [H12971] [H12
2c6c0 39 37 33 5d 20 5b 48 31 32 39 37 35 5d 20 5b 48  973] [H12975] [H
2c6d0 31 32 39 37 37 5d 20 5b 48 31 32 39 37 39 5d 20  12977] [H12979] 
2c6e0 5b 48 31 32 39 38 31 5d 20 5b 48 31 32 39 38 33  [H12981] [H12983
2c6f0 5d 20 5b 48 31 32 39 38 36 5d 0a 2a 2f 0a 76 6f  ] [H12986].*/.vo
2c700 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61  id *sqlite3_upda
2c710 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74  te_hook(.  sqlit
2c720 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  e3*, .  void(*)(
2c730 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72  void *,int ,char
2c740 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f   const *,char co
2c750 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  nst *,sqlite3_in
2c760 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b  t64),.  void*.);
2c770 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c780 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
2c790 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72  ble Shared Pager
2c7a0 20 43 61 63 68 65 20 7b 48 31 30 33 33 30 7d 20   Cache {H10330} 
2c7b0 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S30900>.** KEYW
2c7c0 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61  ORDS: {shared ca
2c7d0 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  che}.**.** This 
2c7e0 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
2c7f0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
2c800 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64  sharing of the d
2c810 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a  atabase cache.**
2c820 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61   and schema data
2c830 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77   structures betw
2c840 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  een [database co
2c850 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65  nnection | conne
2c860 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68  ctions].** to th
2c870 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e  e same database.
2c880 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   Sharing is enab
2c890 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
2c8a0 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61  ent is true.** a
2c8b0 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74  nd disabled if t
2c8c0 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66  he argument is f
2c8d0 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68  alse..**.** Cach
2c8e0 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61  e sharing is ena
2c8f0 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65  bled and disable
2c900 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20  d for an entire 
2c910 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73  process..** This
2c920 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20   is a change as 
2c930 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
2c940 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f  n 3.5.0. In prio
2c950 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
2c960 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67  Lite,.** sharing
2c970 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
2c980 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63  disabled for eac
2c990 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74  h thread separat
2c9a0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ely..**.** The c
2c9b0 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64  ache sharing mod
2c9c0 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e  e set by this in
2c9d0 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20  terface effects 
2c9e0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
2c9f0 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  * calls to [sqli
2ca00 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
2ca10 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2ca20 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  , and [sqlite3_o
2ca30 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69  pen16()]..** Exi
2ca40 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63  sting database c
2ca50 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69  onnections conti
2ca60 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72  nue use the shar
2ca70 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74  ing mode.** that
2ca80 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61   was in effect a
2ca90 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20  t the time they 
2caa0 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  were opened..**.
2cab0 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  ** Virtual table
2cac0 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64  s cannot be used
2cad0 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20 63   with a shared c
2cae0 61 63 68 65 2e 20 20 57 68 65 6e 20 73 68 61 72  ache.  When shar
2caf0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
2cb00 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c  nabled, the [sql
2cb10 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
2cb20 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64 20 74  le()] API used t
2cb30 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69  o register.** vi
2cb40 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c  rtual tables wil
2cb50 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
2cb60 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  an error..**.** 
2cb70 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
2cb80 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
2cb90 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
2cba0 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
2cbb0 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63  disabled.** succ
2cbc0 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65  essfully.  An [e
2cbd0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2cbe0 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65  turned otherwise
2cbf0 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63  ..**.** Shared c
2cc00 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64  ache is disabled
2cc10 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74   by default. But
2cc20 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e   this might chan
2cc30 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  ge in.** future 
2cc40 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
2cc50 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  te.  Application
2cc60 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75  s that care abou
2cc70 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
2cc80 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64  e setting should
2cc90 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74   set it explicit
2cca0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c  ly..**.** See Al
2ccb0 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61  so:  [SQLite Sha
2ccc0 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a  red-Cache Mode].
2ccd0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
2cce0 74 73 3a 20 5b 48 31 30 33 33 31 5d 20 5b 48 31  ts: [H10331] [H1
2ccf0 30 33 33 36 5d 20 5b 48 31 30 33 33 37 5d 20 5b  0336] [H10337] [
2cd00 48 31 30 33 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73  H10339].*/.int s
2cd10 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
2cd20 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b  ared_cache(int);
2cd30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2cd40 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65  : Attempt To Fre
2cd50 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 20 7b 48  e Heap Memory {H
2cd60 31 37 33 34 30 7d 20 3c 53 33 30 32 32 30 3e 0a  17340} <S30220>.
2cd70 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2cd80 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
2cd90 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
2cda0 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20  empts to free N 
2cdb0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70  bytes.** of heap
2cdc0 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c   memory by deall
2cdd0 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65  ocating non-esse
2cde0 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ntial memory all
2cdf0 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64  ocations.** held
2ce00 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
2ce10 20 6c 69 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20   library. {END} 
2ce20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20   Memory used to 
2ce30 63 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a  cache database.*
2ce40 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f  * pages to impro
2ce50 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69  ve performance i
2ce60 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
2ce70 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
2ce80 6d 6f 72 79 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  mory..** sqlite3
2ce90 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2cea0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  ) returns the nu
2ceb0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63  mber of bytes ac
2cec0 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a  tually freed,.**
2ced0 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20   which might be 
2cee0 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61  more or less tha
2cef0 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71  n the amount req
2cf00 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  uested..**.** Re
2cf10 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 37  quirements: [H17
2cf20 33 34 31 5d 20 5b 48 31 37 33 34 32 5d 0a 2a 2f  341] [H17342].*/
2cf30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
2cf40 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
2cf50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2cf60 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69  F: Impose A Limi
2cf70 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20 7b  t On Heap Size {
2cf80 48 31 37 33 35 30 7d 20 3c 53 33 30 32 32 30 3e  H17350} <S30220>
2cf90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2cfa0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
2cfb0 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 70  it() interface p
2cfc0 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c  laces a "soft" l
2cfd0 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61  imit.** on the a
2cfe0 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65  mount of heap me
2cff0 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65  mory that may be
2d000 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
2d010 4c 69 74 65 2e 0a 2a 2a 20 49 66 20 61 6e 20 69  Lite..** If an i
2d020 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69  nternal allocati
2d030 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20  on is requested 
2d040 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65  that would excee
2d050 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65  d the.** soft he
2d060 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74  ap limit, [sqlit
2d070 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
2d080 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20  y()] is invoked 
2d090 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  one or.** more t
2d0a0 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20  imes to free up 
2d0b0 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72  some space befor
2d0c0 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  e the allocation
2d0d0 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a   is performed..*
2d0e0 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69  *.** The limit i
2d0f0 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c  s called "soft",
2d100 20 62 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c   because if [sql
2d110 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2d120 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74  ory()].** cannot
2d130 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74   free sufficient
2d140 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65   memory to preve
2d150 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f  nt the limit fro
2d160 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64  m being exceeded
2d170 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  ,.** the memory 
2d180 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79  is allocated any
2d190 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72  way and the curr
2d1a0 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  ent operation pr
2d1b0 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  oceeds..**.** A 
2d1c0 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f  negative or zero
2d1d0 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61   value for N mea
2d1e0 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73  ns that there is
2d1f0 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69   no soft heap li
2d200 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  mit and.** [sqli
2d210 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2d220 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20  ry()] will only 
2d230 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d  be called when m
2d240 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74  emory is exhaust
2d250 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ed..** The defau
2d260 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  lt value for the
2d270 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2d280 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20   is zero..**.** 
2d290 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62  SQLite makes a b
2d2a0 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f  est effort to ho
2d2b0 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  nor the soft hea
2d2c0 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 74 20  p limit..** But 
2d2d0 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  if the soft heap
2d2e0 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65   limit cannot be
2d2f0 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74   honored, execut
2d300 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  ion will.** cont
2d310 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72  inue without err
2d320 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69  or or notificati
2d330 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79  on.  This is why
2d340 20 74 68 65 20 6c 69 6d 69 74 20 69 73 0a 2a 2a   the limit is.**
2d350 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22   called a "soft"
2d360 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61   limit.  It is a
2d370 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a  dvisory only..**
2d380 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
2d390 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
2d3a0 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  0, this routine 
2d3b0 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64  only constrained
2d3c0 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
2d3d0 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69  llocated by a si
2d3e0 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68  ngle thread - th
2d3f0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2d400 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74   which this rout
2d410 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65  ine.** runs.  Be
2d420 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c  ginning with SQL
2d430 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
2d440 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  0, the soft heap
2d450 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70   limit is.** app
2d460 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65  lied to all thre
2d470 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73  ads. The value s
2d480 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65  pecified for the
2d490 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2d4a0 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20  .** is an upper 
2d4b0 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74  bound on the tot
2d4c0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
2d4d0 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72  tion for all thr
2d4e0 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73  eads. In.** vers
2d4f0 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20  ion 3.5.0 there 
2d500 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20  is no mechanism 
2d510 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65  for limiting the
2d520 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a   heap usage for.
2d530 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68  ** individual th
2d540 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  reads..**.** Req
2d550 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
2d560 31 36 33 35 31 5d 20 5b 48 31 36 33 35 32 5d 20  16351] [H16352] 
2d570 5b 48 31 36 33 35 33 5d 20 5b 48 31 36 33 35 34  [H16353] [H16354
2d580 5d 20 5b 48 31 36 33 35 35 5d 20 5b 48 31 36 33  ] [H16355] [H163
2d590 35 38 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  58].*/.void sqli
2d5a0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
2d5b0 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mit(int);../*.**
2d5c0 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 72 61   CAPI3REF: Extra
2d5d0 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75  ct Metadata Abou
2d5e0 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20  t A Column Of A 
2d5f0 54 61 62 6c 65 20 7b 48 31 32 38 35 30 7d 20 3c  Table {H12850} <
2d600 53 36 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60300>.**.** Th
2d610 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
2d620 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75  ns metadata abou
2d630 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c  t a specific col
2d640 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69  umn of a specifi
2d650 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61  c.** database ta
2d660 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75  ble accessible u
2d670 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61  sing the [databa
2d680 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
2d690 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20  andle.** passed 
2d6a0 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e  as the first fun
2d6b0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2d6c0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e  **.** The column
2d6d0 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62   is identified b
2d6e0 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68  y the second, th
2d6f0 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
2d700 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20  arameters to.** 
2d710 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54  this function. T
2d720 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2d730 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68  ter is either th
2d740 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
2d750 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20  tabase.** (i.e. 
2d760 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f  "main", "temp" o
2d770 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61  r an attached da
2d780 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69  tabase) containi
2d790 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64  ng the specified
2d7a0 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c  .** table or NUL
2d7b0 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  L. If it is NULL
2d7c0 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63  , then all attac
2d7d0 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72  hed databases ar
2d7e0 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f  e searched.** fo
2d7f0 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e  r the table usin
2d800 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
2d810 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65  ithm used by the
2d820 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2d830 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75   to.** resolve u
2d840 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65  nqualified table
2d850 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a   references..**.
2d860 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  ** The third and
2d870 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2d880 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
2d890 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c  ion are the tabl
2d8a0 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  e and column.** 
2d8b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69  name of the desi
2d8c0 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70  red column, resp
2d8d0 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65  ectively. Neithe
2d8e0 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  r of these param
2d8f0 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20  eters.** may be 
2d900 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61  NULL..**.** Meta
2d910 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 64  data is returned
2d920 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74   by writing to t
2d930 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69  he memory locati
2d940 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 68  ons passed as th
2d950 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62  e 5th.** and sub
2d960 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65  sequent paramete
2d970 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
2d980 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 73  ion. Any of thes
2d990 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20  e arguments may 
2d9a0 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77  be.** NULL, in w
2d9b0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f  hich case the co
2d9c0 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d  rresponding elem
2d9d0 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20  ent of metadata 
2d9e0 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a  is omitted..**.*
2d9f0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
2da00 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
2da10 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
2da20 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20   Parameter <th> 
2da30 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c  Output<br>Type <
2da40 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e  th>  Description
2da50 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
2da60 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  5th <td> const c
2da70 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74  har* <td> Data t
2da80 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ype.** <tr><td> 
2da90 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  6th <td> const c
2daa0 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f  har* <td> Name o
2dab0 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74  f default collat
2dac0 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20  ion sequence.** 
2dad0 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64  <tr><td> 7th <td
2dae0 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
2daf0 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
2db00 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c  n has a NOT NULL
2db10 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c   constraint.** <
2db20 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e  tr><td> 8th <td>
2db30 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
2db40 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
2db50 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   is part of the 
2db60 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c  PRIMARY KEY.** <
2db70 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e  tr><td> 9th <td>
2db80 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
2db90 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
2dba0 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45   is [AUTOINCREME
2dbb0 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  NT].** </table>.
2dbc0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
2dbd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72  .**.** The memor
2dbe0 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  y pointed to by 
2dbf0 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f  the character po
2dc00 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
2dc10 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61  for the.** decla
2dc20 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20  ration type and 
2dc30 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2dc40 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79  ce is valid only
2dc50 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a   until the next.
2dc60 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53  ** call to any S
2dc70 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69  QLite API functi
2dc80 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  on..**.** If the
2dc90 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65   specified table
2dca0 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76   is actually a v
2dcb0 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  iew, an [error c
2dcc0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
2dcd0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73  ..**.** If the s
2dce0 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20  pecified column 
2dcf0 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64  is "rowid", "oid
2dd00 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61  " or "_rowid_" a
2dd10 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45  nd an.** [INTEGE
2dd20 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63  R PRIMARY KEY] c
2dd30 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65  olumn has been e
2dd40 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
2dd50 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  ed, then the out
2dd60 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
2dd70 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68  s are set for th
2dd80 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  e explicitly dec
2dd90 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66  lared column. If
2dda0 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20   there is no.** 
2ddb0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
2ddc0 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49  red [INTEGER PRI
2ddd0 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e  MARY KEY] column
2dde0 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75  , then the outpu
2ddf0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  t.** parameters 
2de00 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f  are set as follo
2de10 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  ws:.**.** <pre>.
2de20 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65  **     data type
2de30 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20  : "INTEGER".**  
2de40 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71     collation seq
2de50 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a  uence: "BINARY".
2de60 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a  **     not null:
2de70 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72   0.**     primar
2de80 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20  y key: 1.**     
2de90 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20  auto increment: 
2dea0 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a  0.** </pre>.**.*
2deb0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
2dec0 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20  may load one or 
2ded0 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f  more schemas fro
2dee0 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  m database files
2def0 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  . If an.** error
2df00 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
2df10 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  his process, or 
2df20 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  if the requested
2df30 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
2df40 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f  .** cannot be fo
2df50 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  und, an [error c
2df60 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
2df70 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
2df80 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e  ssage left.** in
2df90 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2dfa0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62  onnection] (to b
2dfb0 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e  e retrieved usin
2dfc0 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  g sqlite3_errmsg
2dfd0 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ())..**.** This 
2dfe0 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  API is only avai
2dff0 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
2e000 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
2e010 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
2e020 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
2e030 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
2e040 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
2e050 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  bol defined..*/.
2e060 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c  int sqlite3_tabl
2e070 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74  e_column_metadat
2e080 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  a(.  sqlite3 *db
2e090 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2e0a0 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68   /* Connection h
2e0b0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2e0c0 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20   char *zDbName, 
2e0d0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2e0e0 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20  se name or NULL 
2e0f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2e100 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20  *zTableName,    
2e110 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a   /* Table name *
2e120 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2e130 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20  zColumnName,    
2e140 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a  /* Column name *
2e150 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
2e160 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20  *pzDataType,    
2e170 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61  /* OUTPUT: Decla
2e180 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f  red data type */
2e190 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
2e1a0 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f  pzCollSeq,     /
2e1b0 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74  * OUTPUT: Collat
2e1c0 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d  ion sequence nam
2e1d0 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74  e */.  int *pNot
2e1e0 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20  Null,           
2e1f0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
2e200 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63  ue if NOT NULL c
2e210 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73  onstraint exists
2e220 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d   */.  int *pPrim
2e230 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20  aryKey,         
2e240 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
2e250 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74  e if column part
2e260 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20   of PK */.  int 
2e270 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20  *pAutoinc       
2e280 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
2e290 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  T: True if colum
2e2a0 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d  n is auto-increm
2e2b0 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ent */.);../*.**
2e2c0 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20   CAPI3REF: Load 
2e2d0 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 48 31  An Extension {H1
2e2e0 32 36 30 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a  2600} <S20500>.*
2e2f0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2e300 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c  ace loads an SQL
2e310 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
2e320 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e  brary from the n
2e330 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  amed file..**.**
2e340 20 7b 48 31 32 36 30 31 7d 20 54 68 65 20 73 71   {H12601} The sq
2e350 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
2e360 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
2e370 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61   attempts to loa
2e380 64 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  d an.**         
2e390 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
2e3a0 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  n library contai
2e3b0 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20  ned in the file 
2e3c0 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  zFile..**.** {H1
2e3d0 32 36 30 32 7d 20 54 68 65 20 65 6e 74 72 79 20  2602} The entry 
2e3e0 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a  point is zProc..
2e3f0 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 33 7d 20 7a  **.** {H12603} z
2e400 50 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69  Proc may be 0, i
2e410 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
2e420 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74   name of the ent
2e430 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 20  ry point.**     
2e440 20 20 20 20 20 64 65 66 61 75 6c 74 73 20 74 6f       defaults to
2e450 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73   "sqlite3_extens
2e460 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a  ion_init"..**.**
2e470 20 7b 48 31 32 36 30 34 7d 20 54 68 65 20 73 71   {H12604} The sq
2e480 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
2e490 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
2e4a0 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a   shall return.**
2e4b0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2e4c0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
2e4d0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52   and [SQLITE_ERR
2e4e0 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67  OR] if something
2e4f0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a   goes wrong..**.
2e500 2a 2a 20 7b 48 31 32 36 30 35 7d 20 49 66 20 61  ** {H12605} If a
2e510 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61  n error occurs a
2e520 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e  nd pzErrMsg is n
2e530 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a  ot 0, then the.*
2e540 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2e550 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
2e560 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  on()] interface 
2e570 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f  shall attempt to
2e580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
2e590 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68  l *pzErrMsg with
2e5a0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
2e5b0 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65  ext stored in me
2e5c0 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  mory.**         
2e5d0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2e5e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2e5f0 5d 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 61  ]. {END}  The ca
2e600 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a  lling function.*
2e610 2a 20 20 20 20 20 20 20 20 20 20 73 68 6f 75 6c  *          shoul
2e620 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f  d free this memo
2e630 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ry by calling [s
2e640 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2e650 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 36 7d 20 45  **.** {H12606} E
2e660 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
2e670 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64   must be enabled
2e680 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
2e690 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62     [sqlite3_enab
2e6a0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
2e6b0 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61  n()] prior to ca
2e6c0 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a  lling this API,.
2e6d0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 74 68 65  **          othe
2e6e0 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 77  rwise an error w
2e6f0 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e  ill be returned.
2e700 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2e710 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a  load_extension(.
2e720 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2e730 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20          /* Load 
2e740 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e  the extension in
2e750 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65  to this database
2e760 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20   connection */. 
2e770 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
2e780 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f  le,    /* Name o
2e790 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62  f the shared lib
2e7a0 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  rary containing 
2e7b0 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63  extension */.  c
2e7c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63  onst char *zProc
2e7d0 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f  ,    /* Entry po
2e7e0 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72  int.  Derived fr
2e7f0 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f  om zFile if 0 */
2e800 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  .  char **pzErrM
2e810 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20  sg       /* Put 
2e820 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65  error message he
2e830 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29  re if not 0 */.)
2e840 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e850 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
2e860 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c  able Extension L
2e870 6f 61 64 69 6e 67 20 7b 48 31 32 36 32 30 7d 20  oading {H12620} 
2e880 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 53  <S20500>.**.** S
2e890 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e  o as not to open
2e8a0 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20   security holes 
2e8b0 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61  in older applica
2e8c0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a  tions that are.*
2e8d0 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20  * unprepared to 
2e8e0 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73  deal with extens
2e8f0 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64  ion loading, and
2e900 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64   as a means of d
2e910 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65  isabling.** exte
2e920 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68  nsion loading wh
2e930 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75  ile evaluating u
2e940 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c  ser-entered SQL,
2e950 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41   the following A
2e960 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65  PI.** is provide
2e970 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73  d to turn the [s
2e980 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
2e990 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69  nsion()] mechani
2e9a0 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a  sm on and off..*
2e9b0 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c  *.** Extension l
2e9c0 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79  oading is off by
2e9d0 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69   default. See ti
2e9e0 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a  cket #1863..**.*
2e9f0 2a 20 7b 48 31 32 36 32 31 7d 20 43 61 6c 6c 20  * {H12621} Call 
2ea00 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  the sqlite3_enab
2ea10 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
2ea20 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68  n() routine with
2ea30 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 20 20 20   onoff==1.**    
2ea40 20 20 20 20 20 20 74 6f 20 74 75 72 6e 20 65 78        to turn ex
2ea50 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
2ea60 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77  on and call it w
2ea70 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20  ith onoff==0 to 
2ea80 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
2ea90 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61   it back off aga
2eaa0 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32  in..**.** {H1262
2eab0 32 7d 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  2} Extension loa
2eac0 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64  ding is off by d
2ead0 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73  efault..*/.int s
2eae0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
2eaf0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c  ad_extension(sql
2eb00 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e  ite3 *db, int on
2eb10 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
2eb20 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63  I3REF: Automatic
2eb30 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74  ally Load An Ext
2eb40 65 6e 73 69 6f 6e 73 20 7b 48 31 32 36 34 30 7d  ensions {H12640}
2eb50 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20500>.**.** 
2eb60 54 68 69 73 20 41 50 49 20 63 61 6e 20 62 65 20  This API can be 
2eb70 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72  invoked at progr
2eb80 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72  am startup in or
2eb90 64 65 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a  der to register.
2eba0 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73  ** one or more s
2ebb0 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64  tatically linked
2ebc0 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74   extensions that
2ebd0 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62   will be availab
2ebe0 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77  le.** to all new
2ebf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2ec00 63 74 69 6f 6e 73 5d 2e 20 7b 45 4e 44 7d 0a 2a  ctions]. {END}.*
2ec10 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
2ec20 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74  e stores a point
2ec30 65 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73  er to the extens
2ec40 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 20  ion in an array 
2ec50 74 68 61 74 20 69 73 0a 2a 2a 20 6f 62 74 61 69  that is.** obtai
2ec60 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2ec70 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 49 66  3_malloc()].  If
2ec80 20 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72   you run a memor
2ec90 79 20 6c 65 61 6b 20 63 68 65 63 6b 65 72 0a 2a  y leak checker.*
2eca0 2a 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61  * on your progra
2ecb0 6d 20 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73  m and it reports
2ecc0 20 61 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20   a leak because 
2ecd0 6f 66 20 74 68 69 73 20 61 72 72 61 79 2c 20 69  of this array, i
2ece0 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  nvoke.** [sqlite
2ecf0 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74  3_reset_auto_ext
2ed00 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20  ension()] prior 
2ed10 74 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 66  to shutdown to f
2ed20 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a  ree the memory..
2ed30 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 31 7d 20 54  **.** {H12641} T
2ed40 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  his function reg
2ed50 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73  isters an extens
2ed60 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  ion entry point 
2ed70 74 68 61 74 20 69 73 0a 2a 2a 20 20 20 20 20 20  that is.**      
2ed80 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c      automaticall
2ed90 79 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  y invoked whenev
2eda0 65 72 20 61 20 6e 65 77 20 5b 64 61 74 61 62 61  er a new [databa
2edb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
2edc0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6f 70  *          is op
2edd0 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ened using [sqli
2ede0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
2edf0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
2ee00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
2ee10 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2ee20 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  ()]..**.** {H126
2ee30 34 32 7d 20 44 75 70 6c 69 63 61 74 65 20 65 78  42} Duplicate ex
2ee40 74 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74  tensions are det
2ee50 65 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67  ected so calling
2ee60 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
2ee70 20 20 20 20 20 20 20 20 20 20 6d 75 6c 74 69 70            multip
2ee80 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  le times with th
2ee90 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e  e same extension
2eea0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a   is harmless..**
2eeb0 0a 2a 2a 20 7b 48 31 32 36 34 33 7d 20 54 68 69  .** {H12643} Thi
2eec0 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
2eed0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2eee0 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61  e extension in a
2eef0 6e 20 61 72 72 61 79 0a 2a 2a 20 20 20 20 20 20  n array.**      
2ef00 20 20 20 20 74 68 61 74 20 69 73 20 6f 62 74 61      that is obta
2ef10 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
2ef20 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
2ef30 0a 2a 2a 20 7b 48 31 32 36 34 34 7d 20 41 75 74  .** {H12644} Aut
2ef40 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
2ef50 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61  s apply across a
2ef60 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 69  ll threads..*/.i
2ef70 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  nt sqlite3_auto_
2ef80 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28  extension(void (
2ef90 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f  *xEntryPoint)(vo
2efa0 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id));../*.** CAP
2efb0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75 74  I3REF: Reset Aut
2efc0 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e  omatic Extension
2efd0 20 4c 6f 61 64 69 6e 67 20 7b 48 31 32 36 36 30   Loading {H12660
2efe0 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20500>.**.**
2eff0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64   This function d
2f000 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76  isables all prev
2f010 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
2f020 64 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 65  d automatic.** e
2f030 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d  xtensions. {END}
2f040 20 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20    It undoes the 
2f050 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72  effect of all pr
2f060 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ior.** [sqlite3_
2f070 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
2f080 5d 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b  ] calls..**.** {
2f090 48 31 32 36 36 31 7d 20 54 68 69 73 20 66 75 6e  H12661} This fun
2f0a0 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61  ction disables a
2f0b0 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ll previously re
2f0c0 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20  gistered.**     
2f0d0 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 20 65       automatic e
2f0e0 78 74 65 6e 73 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  xtensions..**.**
2f0f0 20 7b 48 31 32 36 36 32 7d 20 54 68 69 73 20 66   {H12662} This f
2f100 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73  unction disables
2f110 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e   automatic exten
2f120 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72  sions in all thr
2f130 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  eads..*/.void sq
2f140 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f  lite3_reset_auto
2f150 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29  _extension(void)
2f160 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50  ;../*.****** EXP
2f170 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a  ERIMENTAL - subj
2f180 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
2f190 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a  thout notice ***
2f1a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a  ***********.**.*
2f1b0 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
2f1c0 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
2f1d0 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69  able mechanism i
2f1e0 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
2f1f0 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
2f200 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
2f210 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
2f220 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
2f230 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
2f240 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
2f250 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
2f260 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
2f270 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
2f280 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
2f290 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
2f2a0 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
2f2b0 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69  tabilizes, we wi
2f2c0 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
2f2d0 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
2f2e0 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
2f2f0 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
2f300 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
2f310 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53  ent..*/../*.** S
2f320 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62  tructures used b
2f330 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  y the virtual ta
2f340 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f  ble interface.*/
2f350 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2f360 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c  sqlite3_vtab sql
2f370 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64  ite3_vtab;.typed
2f380 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2f390 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c  3_index_info sql
2f3a0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b  ite3_index_info;
2f3b0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2f3c0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2f3d0 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62  sor sqlite3_vtab
2f3e0 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66  _cursor;.typedef
2f3f0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2f400 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d  module sqlite3_m
2f410 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  odule;../*.** CA
2f420 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
2f430 54 61 62 6c 65 20 4f 62 6a 65 63 74 20 7b 48 31  Table Object {H1
2f440 38 30 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a  8000} <S20400>.*
2f450 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
2f460 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74  te3_module {virt
2f470 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
2f480 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  }.** EXPERIMENTA
2f490 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72  L.**.** This str
2f4a0 75 63 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65  ucture, sometime
2f4b0 73 20 63 61 6c 6c 65 64 20 61 20 61 20 22 76 69  s called a a "vi
2f4c0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
2f4d0 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73  le", .** defines
2f4e0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2f4f0 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 75 61  ion of a [virtua
2f500 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20  l tables].  .** 
2f510 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63  This structure c
2f520 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f  onsists mostly o
2f530 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  f methods for th
2f540 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20  e module..**.** 
2f550 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  A virtual table 
2f560 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61 74 65  module is create
2f570 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20  d by filling in 
2f580 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  a persistent.** 
2f590 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
2f5a0 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 70   structure and p
2f5b0 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 65 72  assing a pointer
2f5c0 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61 6e 63   to that instanc
2f5d0 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  e.** to [sqlite3
2f5e0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29  _create_module()
2f5f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72  ] or [sqlite3_cr
2f600 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
2f610 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 67 69 73 74  ]..** The regist
2f620 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76  ration remains v
2f630 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73  alid until it is
2f640 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 64   replaced by a d
2f650 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75  ifferent.** modu
2f660 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  le or until the 
2f670 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2f680 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54  tion] closes.  T
2f690 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66  he content.** of
2f6a0 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
2f6b0 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20  must not change 
2f6c0 77 68 69 6c 65 20 69 74 20 69 73 20 72 65 67 69  while it is regi
2f6d0 73 74 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61  stered with.** a
2f6e0 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
2f6f0 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63  ection..*/.struc
2f700 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
2f710 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
2f720 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61  n;.  int (*xCrea
2f730 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  te)(sqlite3*, vo
2f740 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
2f750 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
2f760 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
2f770 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
2f780 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
2f790 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
2f7a0 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
2f7b0 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69  (*xConnect)(sqli
2f7c0 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
2f7d0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2f7e0 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
2f7f0 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
2f800 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
2f810 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
2f820 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
2f830 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49  ;.  int (*xBestI
2f840 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74  ndex)(sqlite3_vt
2f850 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
2f860 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b  e3_index_info*);
2f870 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e  .  int (*xDiscon
2f880 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74  nect)(sqlite3_vt
2f890 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2f8a0 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71  t (*xDestroy)(sq
2f8b0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
2f8c0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65  b);.  int (*xOpe
2f8d0 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
2f8e0 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
2f8f0 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70  vtab_cursor **pp
2f900 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28  Cursor);.  int (
2f910 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
2f920 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
2f930 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29    int (*xFilter)
2f940 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
2f950 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75  rsor*, int idxNu
2f960 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69  m, const char *i
2f970 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20  dxStr,.         
2f980 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
2f990 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
2f9a0 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a  *argv);.  int (*
2f9b0 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76  xNext)(sqlite3_v
2f9c0 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
2f9d0 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69  int (*xEof)(sqli
2f9e0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
2f9f0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75  );.  int (*xColu
2fa00 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  mn)(sqlite3_vtab
2fa10 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
2fa20 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
2fa30 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64  ;.  int (*xRowid
2fa40 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
2fa50 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
2fa60 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a  int64 *pRowid);.
2fa70 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29    int (*xUpdate)
2fa80 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c  (sqlite3_vtab *,
2fa90 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61   int, sqlite3_va
2faa0 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f  lue **, sqlite3_
2fab0 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20  int64 *);.  int 
2fac0 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65  (*xBegin)(sqlite
2fad0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
2fae0 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
2faf0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
2fb00 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  ab);.  int (*xCo
2fb10 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74  mmit)(sqlite3_vt
2fb20 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2fb30 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73  t (*xRollback)(s
2fb40 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
2fb50 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ab);.  int (*xFi
2fb60 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69  ndFunction)(sqli
2fb70 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
2fb80 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74   int nArg, const
2fb90 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20   char *zName,.  
2fba0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fbb0 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46       void (**pxF
2fbc0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2fbd0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2fbe0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20  3_value**),.    
2fbf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fc00 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29     void **ppArg)
2fc10 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d  ;.  int (*xRenam
2fc20 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
2fc30 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68  *pVtab, const ch
2fc40 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f  ar *zNew);.};../
2fc50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
2fc60 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64  irtual Table Ind
2fc70 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f  exing Informatio
2fc80 6e 20 7b 48 31 38 31 30 30 7d 20 3c 53 32 30 34  n {H18100} <S204
2fc90 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
2fca0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
2fcb0 6e 66 6f 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  nfo.** EXPERIMEN
2fcc0 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  TAL.**.** The sq
2fcd0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
2fce0 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 69   structure and i
2fcf0 74 73 20 73 75 62 73 74 72 75 63 74 75 72 65 73  ts substructures
2fd00 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70   is used to.** p
2fd10 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ass information 
2fd20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65  into and receive
2fd30 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20   the reply from 
2fd40 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d  the [xBestIndex]
2fd50 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20  .** method of a 
2fd60 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
2fd70 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 65  odule].  The fie
2fd80 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75  lds under **Inpu
2fd90 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20  ts** are the.** 
2fda0 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 49  inputs to xBestI
2fdb0 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 61  ndex and are rea
2fdc0 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e  d-only.  xBestIn
2fdd0 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a  dex inserts its.
2fde0 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
2fdf0 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20  the **Outputs** 
2fe00 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  fields..**.** Th
2fe10 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
2fe20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48  array records WH
2fe30 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
2fe40 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66 6f  raints of the fo
2fe50 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63  rm:.**.** <pre>c
2fe60 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70  olumn OP expr</p
2fe70 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20  re>.**.** where 
2fe80 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26  OP is =, &lt;, &
2fe90 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26  lt;=, &gt;, or &
2fea0 67 74 3b 3d 2e 20 20 54 68 65 20 70 61 72 74 69  gt;=.  The parti
2feb0 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69  cular operator i
2fec0 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61  s.** stored in a
2fed0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e  Constraint[].op.
2fee0 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74    The index of t
2fef0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f  he column is sto
2ff00 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74  red in.** aConst
2ff10 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e  raint[].iColumn.
2ff20 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e    aConstraint[].
2ff30 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69  usable is TRUE i
2ff40 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e  f the.** expr on
2ff50 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
2ff60 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c  side can be eval
2ff70 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20  uated (and thus 
2ff80 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  the constraint.*
2ff90 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64  * is usable) and
2ffa0 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e   false if it can
2ffb0 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  not..**.** The o
2ffc0 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74  ptimizer automat
2ffd0 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74  ically inverts t
2ffe0 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  erms of the form
2fff0 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e   "expr OP column
30000 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f  ".** and makes o
30010 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74  ther simplificat
30020 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52  ions to the WHER
30030 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61  E clause in an a
30040 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74  ttempt to.** get
30050 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63   as many WHERE c
30060 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f  lause terms into
30070 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20   the form shown 
30080 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c  above as possibl
30090 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74  e..** The aConst
300a0 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e  raint[] array on
300b0 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45  ly reports WHERE
300c0 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e   clause terms in
300d0 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20   the correct.** 
300e0 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 20  form that refer 
300f0 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  to the particula
30100 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
30110 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a  being queried..*
30120 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e  *.** Information
30130 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52   about the ORDER
30140 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74   BY clause is st
30150 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79  ored in aOrderBy
30160 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d  []..** Each term
30170 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63   of aOrderBy rec
30180 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66  ords a column of
30190 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
301a0 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ause..**.** The 
301b0 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 74  [xBestIndex] met
301c0 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43  hod must fill aC
301d0 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d  onstraintUsage[]
301e0 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f   with informatio
301f0 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20  n.** about what 
30200 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61  parameters to pa
30210 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20  ss to xFilter.  
30220 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74  If argvIndex>0 t
30230 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74  hen.** the right
30240 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68  -hand side of th
30250 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
30260 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73  aConstraint[] is
30270 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e   evaluated.** an
30280 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72  d becomes the ar
30290 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79  gvIndex-th entry
302a0 20 69 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43   in argv.  If aC
302b0 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d  onstraintUsage[]
302c0 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65  .omit.** is true
302d0 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74  , then the const
302e0 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64  raint is assumed
302f0 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e   to be fully han
30300 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76  dled by the.** v
30310 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64  irtual table and
30320 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20   is not checked 
30330 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e  again by SQLite.
30340 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75  .**.** The idxNu
30350 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c  m and idxPtr val
30360 75 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64  ues are recorded
30370 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f   and passed into
30380 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72   the.** [xFilter
30390 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5b 73 71  ] method..** [sq
303a0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
303b0 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 69 64   used to free id
303c0 78 50 74 72 20 69 66 20 61 6e 64 20 6f 6e 6c 79  xPtr if and only
303d0 20 69 66 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72   iff.** needToFr
303e0 65 65 49 64 78 50 74 72 20 69 73 20 74 72 75 65  eeIdxPtr is true
303f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65  ..**.** The orde
30400 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e  rByConsumed mean
30410 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 66 72  s that output fr
30420 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e  om [xFilter]/[xN
30430 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20  ext] will occur 
30440 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63  in.** the correc
30450 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73  t order to satis
30460 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  fy the ORDER BY 
30470 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e  clause so that n
30480 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f  o separate.** so
30490 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 65  rting step is re
304a0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
304b0 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20  e estimatedCost 
304c0 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69  value is an esti
304d0 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74  mate of the cost
304e0 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a   of doing the.**
304f0 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b   particular look
30500 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e  up.  A full scan
30510 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 68   of a table with
30520 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
30530 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74  d have.** a cost
30540 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79   of N.  A binary
30550 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 62   search of a tab
30560 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20  le of N entries 
30570 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a  should have a.**
30580 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69   cost of approxi
30590 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a  mately log(N)..*
305a0 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
305b0 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20  _index_info {.  
305c0 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69  /* Inputs */.  i
305d0 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20  nt nConstraint; 
305e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
305f0 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69  ber of entries i
30600 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  n aConstraint */
30610 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
30620 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
30630 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43  nt {.     int iC
30640 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20  olumn;          
30650 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e      /* Column on
30660 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
30670 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  of constraint */
30680 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
30690 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20  har op;         
306a0 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70  /* Constraint op
306b0 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75  erator */.     u
306c0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61  nsigned char usa
306d0 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65  ble;     /* True
306e0 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61   if this constra
306f0 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f  int is usable */
30700 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f  .     int iTermO
30710 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20  ffset;          
30720 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c  /* Used internal
30730 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20  ly - xBestIndex 
30740 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f  should ignore */
30750 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e  .  } *aConstrain
30760 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  t;            /*
30770 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20   Table of WHERE 
30780 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
30790 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64  ts */.  int nOrd
307a0 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20  erBy;           
307b0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
307c0 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44  terms in the ORD
307d0 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
307e0 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
307f0 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b  _index_orderby {
30800 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
30810 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
30820 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  /* Column number
30830 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
30840 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20  d char desc;    
30850 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44     /* True for D
30860 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20  ESC.  False for 
30870 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72  ASC. */.  } *aOr
30880 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20  derBy;          
30890 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45       /* The ORDE
308a0 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20  R BY clause */. 
308b0 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20   /* Outputs */. 
308c0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
308d0 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74  index_constraint
308e0 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74  _usage {.    int
308f0 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20   argvIndex;     
30900 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20        /* if >0, 
30910 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61  constraint is pa
30920 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46  rt of argv to xF
30930 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73  ilter */.    uns
30940 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b  igned char omit;
30950 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20        /* Do not 
30960 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20  code a test for 
30970 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
30980 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61  */.  } *aConstra
30990 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74 20  intUsage;.  int 
309a0 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 20  idxNum;         
309b0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
309c0 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69 66   used to identif
309d0 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20  y the index */. 
309e0 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20 20   char *idxStr;  
309f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
30a00 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20  tring, possibly 
30a10 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
30a20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a  lite3_malloc */.
30a30 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 65    int needToFree
30a40 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a 20  IdxStr;      /* 
30a50 46 72 65 65 20 69 64 78 53 74 72 20 75 73 69 6e  Free idxStr usin
30a60 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
30a70 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e   if true */.  in
30a80 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65  t orderByConsume
30a90 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65  d;       /* True
30aa0 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 61 6c   if output is al
30ab0 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a 2f  ready ordered */
30ac0 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61  .  double estima
30ad0 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a  tedCost;      /*
30ae0 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74 20   Estimated cost 
30af0 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 69 6e  of using this in
30b00 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e  dex */.};.#defin
30b10 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
30b20 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20 20  ONSTRAINT_EQ    
30b30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
30b40 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
30b50 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69 6e  T_GT    4.#defin
30b60 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
30b70 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 20  ONSTRAINT_LE    
30b80 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
30b90 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
30ba0 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66 69  T_LT    16.#defi
30bb0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
30bc0 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20  CONSTRAINT_GE   
30bd0 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   32.#define SQLI
30be0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
30bf0 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a  INT_MATCH 64../*
30c00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
30c10 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c  gister A Virtual
30c20 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74   Table Implement
30c30 61 74 69 6f 6e 20 7b 48 31 38 32 30 30 7d 20 3c  ation {H18200} <
30c40 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S20400>.** EXPER
30c50 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
30c60 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
30c70 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ed to register a
30c80 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61   new [virtual ta
30c90 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65  ble module] name
30ca0 2e 0a 2a 2a 20 4d 6f 64 75 6c 65 20 6e 61 6d 65  ..** Module name
30cb0 73 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74  s must be regist
30cc0 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63  ered before.** c
30cd0 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76  reating a new [v
30ce0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73  irtual table] us
30cf0 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20  ing the module, 
30d00 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20  or before using 
30d10 61 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67  a.** preexisting
30d20 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
30d30 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
30d40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 6f 64 75 6c  .**.** The modul
30d50 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74  e name is regist
30d60 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74  ered on the [dat
30d70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30d80 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  ] specified.** b
30d90 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
30da0 6d 65 74 65 72 2e 20 20 54 68 65 20 6e 61 6d 65  meter.  The name
30db0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
30dc0 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 0a  s given by the .
30dd0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
30de0 74 65 72 2e 20 20 54 68 65 20 74 68 69 72 64 20  ter.  The third 
30df0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
30e00 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ointer to.** the
30e10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30e20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
30e30 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
30e40 20 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70   The fourth.** p
30e50 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
30e60 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20  rbitrary client 
30e70 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61  data pointer tha
30e80 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
30e90 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ugh.** into the 
30ea0 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78  [xCreate] and [x
30eb0 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73  Connect] methods
30ec0 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   of the virtual 
30ed0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20  table module.** 
30ee0 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75  when a new virtu
30ef0 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20 62  al table is be b
30f00 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20  eing created or 
30f10 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a  reinitialized..*
30f20 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
30f30 61 63 65 20 68 61 73 20 65 78 61 63 74 6c 79 20  ace has exactly 
30f40 74 68 65 20 73 61 6d 65 20 65 66 66 65 63 74 20  the same effect 
30f50 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73  as calling.** [s
30f60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
30f70 64 75 6c 65 5f 76 32 28 29 5d 20 77 69 74 68 20  dule_v2()] with 
30f80 61 20 4e 55 4c 4c 20 63 6c 69 65 6e 74 20 64 61  a NULL client da
30f90 74 61 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a  ta destructor..*
30fa0 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  /.SQLITE_EXPERIM
30fb0 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65  ENTAL int sqlite
30fc0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
30fd0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
30fe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
30ff0 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69   SQLite connecti
31000 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  on to register m
31010 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20  odule with */.  
31020 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
31030 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  e,         /* Na
31040 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
31050 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69   */.  const sqli
31060 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20  te3_module *p,  
31070 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
31080 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
31090 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74  void *pClientDat
310a0 61 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c  a          /* Cl
310b0 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43  ient data for xC
310c0 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a  reate/xConnect *
310d0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
310e0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
310f0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
31100 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48  mplementation {H
31110 31 38 32 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a  18210} <S20400>.
31120 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
31130 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
31140 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  ne is identical 
31150 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
31160 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
31170 20 6d 65 74 68 6f 64 2c 0a 2a 2a 20 65 78 63 65   method,.** exce
31180 70 74 20 74 68 61 74 20 69 74 20 68 61 73 20 61  pt that it has a
31190 6e 20 65 78 74 72 61 20 70 61 72 61 6d 65 74 65  n extra paramete
311a0 72 20 74 6f 20 73 70 65 63 69 66 79 20 0a 2a 2a  r to specify .**
311b0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 75   a destructor fu
311c0 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 63  nction for the c
311d0 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74  lient data point
311e0 65 72 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  er.  SQLite will
311f0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  .** invoke the d
31200 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
31210 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74  on (if it is not
31220 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69   NULL) when SQLi
31230 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20  te.** no longer 
31240 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e  needs the pClien
31250 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20  tData pointer.  
31260 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
31270 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69  IMENTAL int sqli
31280 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
31290 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
312a0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
312b0 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e     /* SQLite con
312c0 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73  nection to regis
312d0 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20  ter module with 
312e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
312f0 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  *zName,         
31300 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d  /* Name of the m
31310 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  odule */.  const
31320 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
31330 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *p,   /* Methods
31340 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20   for the module 
31350 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65  */.  void *pClie
31360 6e 74 44 61 74 61 2c 20 20 20 20 20 20 20 20 20  ntData,         
31370 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66  /* Client data f
31380 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e  or xCreate/xConn
31390 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78  ect */.  void(*x
313a0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20  Destroy)(void*) 
313b0 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65      /* Module de
313c0 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
313d0 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  n */.);../*.** C
313e0 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
313f0 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20   Table Instance 
31400 4f 62 6a 65 63 74 20 7b 48 31 38 30 31 30 7d 20  Object {H18010} 
31410 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S20400>.** KEYW
31420 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74  ORDS: sqlite3_vt
31430 61 62 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ab.** EXPERIMENT
31440 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b  AL.**.** Every [
31450 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
31460 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61  dule] implementa
31470 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63  tion uses a subc
31480 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 65 20 66  lass.** of the f
31490 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75  ollowing structu
314a0 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 61  re to describe a
314b0 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74   particular inst
314c0 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ance.** of the [
314d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20  virtual table]. 
314e0 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77   Each subclass w
314f0 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72  ill.** be tailor
31500 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  ed to the specif
31510 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20  ic needs of the 
31520 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
31530 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75  ation..** The pu
31540 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75  rpose of this su
31550 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64  perclass is to d
31560 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69  efine certain fi
31570 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  elds that are.**
31580 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d   common to all m
31590 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
315a0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72  tions..**.** Vir
315b0 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68  tual tables meth
315c0 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65  ods can set an e
315d0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20  rror message by 
315e0 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73  assigning a.** s
315f0 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
31600 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
31610 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d  intf()] to zErrM
31620 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20  sg.  The method 
31630 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63  should.** take c
31640 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69  are that any pri
31650 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65  or string is fre
31660 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20  ed by a call to 
31670 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
31680 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73  .** prior to ass
31690 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72  igning a new str
316a0 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ing to zErrMsg. 
316b0 20 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72   After the error
316c0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64   message.** is d
316d0 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74  elivered up to t
316e0 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63  he client applic
316f0 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e  ation, the strin
31700 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  g will be automa
31710 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64  tically.** freed
31720 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65   by sqlite3_free
31730 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d  () and the zErrM
31740 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65  sg field will be
31750 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75   zeroed..*/.stru
31760 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  ct sqlite3_vtab 
31770 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  {.  const sqlite
31780 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c  3_module *pModul
31790 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c  e;  /* The modul
317a0 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75  e for this virtu
317b0 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e  al table */.  in
317c0 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20  t nRef;         
317d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
317e0 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44 20   NO LONGER USED 
317f0 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d  */.  char *zErrM
31800 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  sg;             
31810 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65       /* Error me
31820 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74  ssage from sqlit
31830 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a  e3_mprintf() */.
31840 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
31850 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
31860 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c  ns will typicall
31870 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
31880 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f   fields */.};../
31890 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
318a0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72  irtual Table Cur
318b0 73 6f 72 20 4f 62 6a 65 63 74 20 20 7b 48 31 38  sor Object  {H18
318c0 30 32 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a  020} <S20400>.**
318d0 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
318e0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b  e3_vtab_cursor {
318f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75  virtual table cu
31900 72 73 6f 72 7d 0a 2a 2a 20 45 58 50 45 52 49 4d  rsor}.** EXPERIM
31910 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72  ENTAL.**.** Ever
31920 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  y [virtual table
31930 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65   module] impleme
31940 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73  ntation uses a s
31950 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
31960 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75  * following stru
31970 63 74 75 72 65 20 74 6f 20 64 65 73 63 72 69 62  cture to describ
31980 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70  e cursors that p
31990 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  oint into the.**
319a0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
319b0 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a   and are used.**
319c0 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68   to loop through
319d0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
319e0 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65  le.  Cursors are
319f0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74   created using t
31a00 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
31a10 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f  odule.xOpen | xO
31a20 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74  pen] method of t
31a30 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72  he module and ar
31a40 65 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62  e destroyed.** b
31a50 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  y the [sqlite3_m
31a60 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78  odule.xClose | x
31a70 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20  Close] method.  
31a80 43 75 73 73 6f 72 73 20 61 72 65 20 75 73 65 64  Cussors are used
31a90 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78 46 69 6c  .** by the [xFil
31aa0 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b  ter], [xNext], [
31ab0 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d  xEof], [xColumn]
31ac0 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d  , and [xRowid] m
31ad0 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65  ethods.** of the
31ae0 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d   module.  Each m
31af0 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
31b00 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65  tion will define
31b10 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
31b20 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75  of a cursor stru
31b30 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74  cture to suit it
31b40 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a  s own needs..**.
31b50 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61  ** This supercla
31b60 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64  ss exists in ord
31b70 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65  er to define fie
31b80 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f  lds of the curso
31b90 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f  r that.** are co
31ba0 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c  mmon to all impl
31bb0 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a  ementations..*/.
31bc0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
31bd0 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73  tab_cursor {.  s
31be0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
31bf0 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74  ab;      /* Virt
31c00 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69  ual table of thi
31c10 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a  s cursor */.  /*
31c20 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
31c30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
31c40 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
31c50 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
31c60 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
31c70 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
31c80 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66  re The Schema Of
31c90 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
31ca0 20 7b 48 31 38 32 38 30 7d 20 3c 53 32 30 34 30   {H18280} <S2040
31cb0 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
31cc0 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 43  AL.**.** The [xC
31cd0 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e  reate] and [xCon
31ce0 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66  nect] methods of
31cf0 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74   a.** [virtual t
31d00 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c  able module] cal
31d10 6c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  l this interface
31d20 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74  .** to declare t
31d30 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e  he format (the n
31d40 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70  ames and datatyp
31d50 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
31d60 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72  s) of.** the vir
31d70 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79  tual tables they
31d80 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 53   implement..*/.S
31d90 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
31da0 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  AL int sqlite3_d
31db0 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69  eclare_vtab(sqli
31dc0 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  te3*, const char
31dd0 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20   *zSQL);../*.** 
31de0 43 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f  CAPI3REF: Overlo
31df0 61 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f  ad A Function Fo
31e00 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  r A Virtual Tabl
31e10 65 20 7b 48 31 38 33 30 30 7d 20 3c 53 32 30 34  e {H18300} <S204
31e20 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
31e30 54 41 4c 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  TAL.**.** Virtua
31e40 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f  l tables can pro
31e50 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65  vide alternative
31e60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
31e70 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
31e80 20 75 73 69 6e 67 20 74 68 65 20 5b 78 46 69 6e   using the [xFin
31e90 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f  dFunction] metho
31ea0 64 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61  d of the [virtua
31eb0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e  l table module].
31ec0 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c    .** But global
31ed0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f   versions of tho
31ee0 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  se functions.** 
31ef0 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72  must exist in or
31f00 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f  der to be overlo
31f10 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  aded..**.** This
31f20 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20   API makes sure 
31f30 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e  a global version
31f40 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77   of a function w
31f50 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
31f60 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d  .** name and num
31f70 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72  ber of parameter
31f80 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f  s exists.  If no
31f90 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65   such function e
31fa0 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20  xists.** before 
31fb0 74 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c  this API is call
31fc0 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69  ed, a new functi
31fd0 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e 20 20  on is created.  
31fe0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
31ff0 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77  on.** of the new
32000 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73   function always
32010 20 63 61 75 73 65 73 20 61 6e 20 65 78 63 65 70   causes an excep
32020 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77  tion to be throw
32030 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65  n.  So.** the ne
32040 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f  w function is no
32050 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68  t good for anyth
32060 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20  ing by itself.  
32070 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70  Its only.** purp
32080 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61 20 70  ose is to be a p
32090 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e 63 74  laceholder funct
320a0 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20  ion that can be 
320b0 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79  overloaded.** by
320c0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
320d0 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  e]..*/.SQLITE_EX
320e0 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73  PERIMENTAL int s
320f0 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f  qlite3_overload_
32100 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33  function(sqlite3
32110 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
32120 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41  FuncName, int nA
32130 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  rg);../*.** The 
32140 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
32150 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
32160 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64  echanism defined
32170 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a   above (back up.
32180 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20  ** to a comment 
32190 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c  remarkably simil
321a0 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20  ar to this one) 
321b0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
321c0 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65  sidered.** to be
321d0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20   experimental.  
321e0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69  The interface mi
321f0 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e  ght change in in
32200 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e  compatible ways.
32210 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61  .** If this is a
32220 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75   problem for you
32230 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65  , do not use the
32240 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68   interface at th
32250 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57  is time..**.** W
32260 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d  hen the virtual-
32270 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
32280 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77  stabilizes, we w
32290 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a  ill declare the.
322a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78  ** interface fix
322b0 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69  ed, support it i
322c0 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64  ndefinitely, and
322d0 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d   remove this com
322e0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20  ment..**.****** 
322f0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73  EXPERIMENTAL - s
32300 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
32310 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20   without notice 
32320 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a  **************.*
32330 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
32340 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41  F: A Handle To A
32350 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37  n Open BLOB {H17
32360 38 30 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a  800} <S30230>.**
32370 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42   KEYWORDS: {BLOB
32380 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68   handle} {BLOB h
32390 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  andles}.**.** An
323a0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
323b0 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
323c0 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42  nts an open BLOB
323d0 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71   on which.** [sq
323e0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
323f0 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
32400 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70  OB I/O] can be p
32410 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a  erformed..** Obj
32420 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70  ects of this typ
32430 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79  e are created by
32440 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
32450 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65  pen()].** and de
32460 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
32470 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
32480 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
32490 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20  e3_blob_read()] 
324a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  and [sqlite3_blo
324b0 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72  b_write()] inter
324c0 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20  faces.** can be 
324d0 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20  used to read or 
324e0 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73  write small subs
324f0 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42  ections of the B
32500 4c 4f 42 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  LOB..** The [sql
32510 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
32520 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
32530 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
32540 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74   the BLOB in byt
32550 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  es..*/.typedef s
32560 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c  truct sqlite3_bl
32570 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b  ob sqlite3_blob;
32580 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32590 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f  : Open A BLOB Fo
325a0 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f  r Incremental I/
325b0 4f 20 7b 48 31 37 38 31 30 7d 20 3c 53 33 30 32  O {H17810} <S302
325c0 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  30>.**.** This i
325d0 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20  nterfaces opens 
325e0 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c  a [BLOB handle |
325f0 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20   handle] to the 
32600 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20  BLOB located.** 
32610 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c  in row iRow, col
32620 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62  umn zColumn, tab
32630 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74  le zTable in dat
32640 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e  abase zDb;.** in
32650 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
32660 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74  e same BLOB that
32670 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74   would be select
32680 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  ed by:.**.** <pr
32690 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54  e>.**     SELECT
326a0 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44   zColumn FROM zD
326b0 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b  b.zTable WHERE [
326c0 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a  rowid] = iRow;.*
326d0 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a  * </pre> {END}.*
326e0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67  *.** If the flag
326f0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  s parameter is n
32700 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
32710 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64  e BLOB is opened
32720 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64   for read.** and
32730 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 49   write access. I
32740 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68  f it is zero, th
32750 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64  e BLOB is opened
32760 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 73 73   for read access
32770 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
32780 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  t the database n
32790 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66  ame is not the f
327a0 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e  ilename that con
327b0 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74  tains.** the dat
327c0 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72  abase but rather
327d0 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61   the symbolic na
327e0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
327f0 73 65 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 73  se that.** is as
32800 73 69 67 6e 65 64 20 77 68 65 6e 20 74 68 65 20  signed when the 
32810 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e  database is conn
32820 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54  ected using [ATT
32830 41 43 48 5d 2e 0a 2a 2a 20 46 6f 72 20 74 68 65  ACH]..** For the
32840 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
32850 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73  ile, the databas
32860 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22  e name is "main"
32870 2e 0a 2a 2a 20 46 6f 72 20 54 45 4d 50 20 74 61  ..** For TEMP ta
32880 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62 61  bles, the databa
32890 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70  se name is "temp
328a0 22 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63  "..**.** On succ
328b0 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
328c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
328d0 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68   the new [BLOB h
328e0 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65  andle] is writte
328f0 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e  n.** to *ppBlob.
32900 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
32910 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
32920 74 75 72 6e 65 64 20 61 6e 64 20 2a 70 70 42 6c  turned and *ppBl
32930 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  ob is set.** to 
32940 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65  be a null pointe
32950 72 2e 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  r..** This funct
32960 69 6f 6e 20 73 65 74 73 20 74 68 65 20 5b 64 61  ion sets the [da
32970 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32980 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  n] error code an
32990 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63  d message.** acc
329a0 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c  essible via [sql
329b0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
329c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
329d0 6d 73 67 28 29 5d 20 61 6e 64 20 72 65 6c 61 74  msg()] and relat
329e0 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e  ed.** functions.
329f0 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
32a00 2a 70 70 42 6c 6f 62 20 76 61 72 69 61 62 6c 65  *ppBlob variable
32a10 20 69 73 20 61 6c 77 61 79 73 20 69 6e 69 74 69   is always initi
32a20 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a 2a 20 77  alized in a.** w
32a30 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 69 74  ay that makes it
32a40 20 73 61 66 65 20 74 6f 20 69 6e 76 6f 6b 65 20   safe to invoke 
32a50 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
32a60 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f  ose()] on *ppBlo
32a70 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  b.** regardless 
32a80 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 20 6f  of the success o
32a90 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 69  r failure of thi
32aa0 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a  s routine..**.**
32ab0 20 49 66 20 74 68 65 20 72 6f 77 20 74 68 61 74   If the row that
32ac0 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 70   a BLOB handle p
32ad0 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f 64 69  oints to is modi
32ae0 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20 5b 55  fied by an.** [U
32af0 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d  PDATE], [DELETE]
32b00 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f 4e 46  , or by [ON CONF
32b10 4c 49 43 54 5d 20 73 69 64 65 2d 65 66 66 65 63  LICT] side-effec
32b20 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 42  ts.** then the B
32b30 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6d 61  LOB handle is ma
32b40 72 6b 65 64 20 61 73 20 22 65 78 70 69 72 65 64  rked as "expired
32b50 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 74 72  "..** This is tr
32b60 75 65 20 69 66 20 61 6e 79 20 63 6f 6c 75 6d 6e  ue if any column
32b70 20 6f 66 20 74 68 65 20 72 6f 77 20 69 73 20 63   of the row is c
32b80 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 61 20 63  hanged, even a c
32b90 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 74  olumn.** other t
32ba0 68 61 6e 20 74 68 65 20 6f 6e 65 20 74 68 65 20  han the one the 
32bb0 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6f  BLOB handle is o
32bc0 70 65 6e 20 6f 6e 2e 0a 2a 2a 20 43 61 6c 6c 73  pen on..** Calls
32bd0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
32be0 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73  b_read()] and [s
32bf0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
32c00 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78  e()] for.** a ex
32c10 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c  pired BLOB handl
32c20 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 72  e fail with an r
32c30 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53  eturn code of [S
32c40 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
32c50 20 43 68 61 6e 67 65 73 20 77 72 69 74 74 65 6e   Changes written
32c60 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 69   into a BLOB pri
32c70 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 65  or to the BLOB e
32c80 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a  xpiring are not.
32c90 2a 2a 20 72 6f 6c 6c 62 61 63 6b 20 62 79 20 74  ** rollback by t
32ca0 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66  he expiration of
32cb0 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68   the BLOB.  Such
32cc0 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76   changes will ev
32cd0 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d  entually.** comm
32ce0 69 74 20 69 66 20 74 68 65 20 74 72 61 6e 73 61  it if the transa
32cf0 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20  ction continues 
32d00 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
32d10 2a 0a 2a 2a 20 55 73 65 20 74 68 65 20 5b 73 71  *.** Use the [sq
32d20 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
32d30 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
32d40 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73   determine the s
32d50 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  ize of.** the op
32d60 65 6e 65 64 20 62 6c 6f 62 2e 20 20 54 68 65 20  ened blob.  The 
32d70 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 6d  size of a blob m
32d80 61 79 20 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  ay not be change
32d90 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 69 6e 74  d by this.** int
32da0 65 72 66 61 63 65 2e 20 20 55 73 65 20 74 68 65  erface.  Use the
32db0 20 5b 55 50 44 41 54 45 5d 20 53 51 4c 20 63 6f   [UPDATE] SQL co
32dc0 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e 67 65 20  mmand to change 
32dd0 74 68 65 20 73 69 7a 65 20 6f 66 20 61 0a 2a 2a  the size of a.**
32de0 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   blob..**.** The
32df0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a   [sqlite3_bind_z
32e00 65 72 6f 62 6c 6f 62 28 29 5d 20 61 6e 64 20 5b  eroblob()] and [
32e10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
32e20 65 72 6f 62 6c 6f 62 28 29 5d 20 69 6e 74 65 72  eroblob()] inter
32e30 66 61 63 65 73 0a 2a 2a 20 61 6e 64 20 74 68 65  faces.** and the
32e40 20 62 75 69 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62   built-in [zerob
32e50 6c 6f 62 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f  lob] SQL functio
32e60 6e 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 69  n can be used, i
32e70 66 20 64 65 73 69 72 65 64 2c 0a 2a 2a 20 74 6f  f desired,.** to
32e80 20 63 72 65 61 74 65 20 61 6e 20 65 6d 70 74 79   create an empty
32e90 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65 64 20 62 6c  , zero-filled bl
32ea0 6f 62 20 69 6e 20 77 68 69 63 68 20 74 6f 20 72  ob in which to r
32eb0 65 61 64 20 6f 72 20 77 72 69 74 65 20 75 73 69  ead or write usi
32ec0 6e 67 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72  ng.** this inter
32ed0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  face..**.** To a
32ee0 76 6f 69 64 20 61 20 72 65 73 6f 75 72 63 65 20  void a resource 
32ef0 6c 65 61 6b 2c 20 65 76 65 72 79 20 6f 70 65 6e  leak, every open
32f00 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 73   [BLOB handle] s
32f10 68 6f 75 6c 64 20 65 76 65 6e 74 75 61 6c 6c 79  hould eventually
32f20 0a 2a 2a 20 62 65 20 72 65 6c 65 61 73 65 64 20  .** be released 
32f30 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  by a call to [sq
32f40 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
32f50 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ()]..**.** Requi
32f60 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37  rements:.** [H17
32f70 38 31 33 5d 20 5b 48 31 37 38 31 34 5d 20 5b 48  813] [H17814] [H
32f80 31 37 38 31 36 5d 20 5b 48 31 37 38 31 39 5d 20  17816] [H17819] 
32f90 5b 48 31 37 38 32 31 5d 20 5b 48 31 37 38 32 34  [H17821] [H17824
32fa0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
32fb0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71  _blob_open(.  sq
32fc0 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20  lite3*,.  const 
32fd0 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e  char *zDb,.  con
32fe0 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c  st char *zTable,
32ff0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
33000 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65  Column,.  sqlite
33010 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20  3_int64 iRow,.  
33020 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c  int flags,.  sql
33030 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c  ite3_blob **ppBl
33040 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ob.);../*.** CAP
33050 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 42  I3REF: Close A B
33060 4c 4f 42 20 48 61 6e 64 6c 65 20 7b 48 31 37 38  LOB Handle {H178
33070 33 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a  30} <S30230>.**.
33080 2a 2a 20 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65  ** Closes an ope
33090 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e  n [BLOB handle].
330a0 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 61  .**.** Closing a
330b0 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73   BLOB shall caus
330c0 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72  e the current tr
330d0 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d  ansaction to com
330e0 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20  mit.** if there 
330f0 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f  are no other BLO
33100 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70  Bs, no pending p
33110 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33120 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64  ts, and the.** d
33130 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33140 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f  on is in [autoco
33150 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 49  mmit mode]..** I
33160 66 20 61 6e 79 20 77 72 69 74 65 73 20 77 65 72  f any writes wer
33170 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42 4c  e made to the BL
33180 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20 62  OB, they might b
33190 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65 0a  e held in cache.
331a0 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f  ** until the clo
331b0 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 20  se operation if 
331c0 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 0a 2a  they will fit..*
331d0 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 74 68 65  *.** Closing the
331e0 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63   BLOB often forc
331f0 65 73 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a  es the changes.*
33200 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e  * out to disk an
33210 64 20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20  d so if any I/O 
33220 65 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68  errors occur, th
33230 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f  ey will likely o
33240 63 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74  ccur.** at the t
33250 69 6d 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f  ime when the BLO
33260 42 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e  B is closed.  An
33270 79 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  y errors that oc
33280 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c  cur during.** cl
33290 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74  osing are report
332a0 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  ed as a non-zero
332b0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a   return value..*
332c0 2a 0a 2a 2a 20 54 68 65 20 42 4c 4f 42 20 69 73  *.** The BLOB is
332d0 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74   closed uncondit
332e0 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69  ionally.  Even i
332f0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  f this routine r
33300 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72  eturns.** an err
33310 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f  or code, the BLO
33320 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65  B is still close
33330 64 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  d..**.** Calling
33340 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
33350 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65  th a null pointe
33360 72 20 28 77 68 69 63 68 20 61 73 20 77 6f 75 6c  r (which as woul
33370 64 20 62 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  d be returned.**
33380 20 62 79 20 66 61 69 6c 65 64 20 63 61 6c 6c 20   by failed call 
33390 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
333a0 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20 61 20 68  _open()]) is a h
333b0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
333c0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
333d0 73 3a 0a 2a 2a 20 5b 48 31 37 38 33 33 5d 20 5b  s:.** [H17833] [
333e0 48 31 37 38 33 36 5d 20 5b 48 31 37 38 33 39 5d  H17836] [H17839]
333f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
33400 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74  blob_close(sqlit
33410 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a  e3_blob *);../*.
33420 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
33430 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20  urn The Size Of 
33440 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31  An Open BLOB {H1
33450 37 38 34 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a  7840} <S30230>.*
33460 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65  *.** Returns the
33470 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f   size in bytes o
33480 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63 65 73  f the BLOB acces
33490 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 0a 2a  sible via the .*
334a0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f  * successfully o
334b0 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64  pened [BLOB hand
334c0 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20  le] in its only 
334d0 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 0a 2a  argument.  The.*
334e0 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62 6c  * incremental bl
334f0 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73 20  ob I/O routines 
33500 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f 72  can only read or
33510 20 6f 76 65 72 77 72 69 74 69 6e 67 20 65 78 69   overwriting exi
33520 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63 6f  sting.** blob co
33530 6e 74 65 6e 74 3b 20 74 68 65 79 20 63 61 6e 6e  ntent; they cann
33540 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 73 69  ot change the si
33550 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a 2a  ze of a blob..**
33560 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
33570 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61   only works on a
33580 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77   [BLOB handle] w
33590 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72  hich has been cr
335a0 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72  eated.** by a pr
335b0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
335c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
335d0 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  blob_open()] and
335e0 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a   which has not.*
335f0 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79  * been closed by
33600 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
33610 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e  lose()].  Passin
33620 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e  g any other poin
33630 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69  ter in.** to thi
33640 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74  s routine result
33650 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  s in undefined a
33660 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
33670 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
33680 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
33690 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 34 33  ents:.** [H17843
336a0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
336b0 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c 69  _blob_bytes(sqli
336c0 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a  te3_blob *);../*
336d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
336e0 61 64 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42  ad Data From A B
336f0 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c  LOB Incrementall
33700 79 20 7b 48 31 37 38 35 30 7d 20 3c 53 33 30 32  y {H17850} <S302
33710 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  30>.**.** This f
33720 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20  unction is used 
33730 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 72 6f  to read data fro
33740 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20  m an open [BLOB 
33750 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a  handle] into a.*
33760 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65  * caller-supplie
33770 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65  d buffer. N byte
33780 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f  s of data are co
33790 70 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72  pied into buffer
337a0 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 6f   Z.** from the o
337b0 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69  pen BLOB, starti
337c0 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66  ng at offset iOf
337d0 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f  fset..**.** If o
337e0 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73  ffset iOffset is
337f0 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74   less than N byt
33800 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20  es from the end 
33810 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20  of the BLOB,.** 
33820 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
33830 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e  s returned and n
33840 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 20  o data is read. 
33850 20 49 66 20 4e 20 6f 72 20 69 4f 66 66 73 65 74   If N or iOffset
33860 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e   is.** less than
33870 20 7a 65 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45   zero, [SQLITE_E
33880 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
33890 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
338a0 20 72 65 61 64 2e 0a 2a 2a 20 54 68 65 20 73 69   read..** The si
338b0 7a 65 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 28  ze of the blob (
338c0 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61  and hence the ma
338d0 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e  ximum value of N
338e0 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e  +iOffset).** can
338f0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
33900 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
33910 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
33920 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
33930 20 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72   An attempt to r
33940 65 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 70 69  ead from an expi
33950 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  red [BLOB handle
33960 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a  ] fails with an.
33970 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66  ** error code of
33980 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
33990 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73  .**.** On succes
339a0 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20  s, SQLITE_OK is 
339b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68  returned..** Oth
339c0 65 72 77 69 73 65 2c 20 61 6e 20 5b 65 72 72 6f  erwise, an [erro
339d0 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65  r code] or an [e
339e0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
339f0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
33a00 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
33a10 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f  ine only works o
33a20 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  n a [BLOB handle
33a30 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e  ] which has been
33a40 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61   created.** by a
33a50 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
33a60 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
33a70 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
33a80 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f  and which has no
33a90 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64  t.** been closed
33aa0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
33ab0 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73  b_close()].  Pas
33ac0 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70  sing any other p
33ad0 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20  ointer in.** to 
33ae0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73  this routine res
33af0 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
33b00 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
33b10 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
33b20 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ior..**.** See a
33b30 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  lso: [sqlite3_bl
33b40 6f 62 5f 77 72 69 74 65 28 29 5d 2e 0a 2a 2a 0a  ob_write()]..**.
33b50 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
33b60 0a 2a 2a 20 5b 48 31 37 38 35 33 5d 20 5b 48 31  .** [H17853] [H1
33b70 37 38 35 36 5d 20 5b 48 31 37 38 35 39 5d 20 5b  7856] [H17859] [
33b80 48 31 37 38 36 32 5d 20 5b 48 31 37 38 36 33 5d  H17862] [H17863]
33b90 20 5b 48 31 37 38 36 35 5d 20 5b 48 31 37 38 36   [H17865] [H1786
33ba0 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  8].*/.int sqlite
33bb0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69  3_blob_read(sqli
33bc0 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64  te3_blob *, void
33bd0 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20   *Z, int N, int 
33be0 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a  iOffset);../*.**
33bf0 20 43 41 50 49 33 52 45 46 3a 20 57 72 69 74 65   CAPI3REF: Write
33c00 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f   Data Into A BLO
33c10 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20  B Incrementally 
33c20 7b 48 31 37 38 37 30 7d 20 3c 53 33 30 32 33 30  {H17870} <S30230
33c30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  >.**.** This fun
33c40 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ction is used to
33c50 20 77 72 69 74 65 20 64 61 74 61 20 69 6e 74 6f   write data into
33c60 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68   an open [BLOB h
33c70 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a  andle] from a.**
33c80 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64   caller-supplied
33c90 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65 73   buffer. N bytes
33ca0 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70   of data are cop
33cb0 69 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66  ied from the buf
33cc0 66 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68  fer Z.** into th
33cd0 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61  e open BLOB, sta
33ce0 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20  rting at offset 
33cf0 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49  iOffset..**.** I
33d00 66 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64  f the [BLOB hand
33d10 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 74 68  le] passed as th
33d20 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
33d30 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20   was not opened 
33d40 66 6f 72 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28  for.** writing (
33d50 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
33d60 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
33d70 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73  blob_open()] was
33d80 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20   zero),.** this 
33d90 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
33da0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   [SQLITE_READONL
33db0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  Y]..**.** This f
33dc0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79  unction may only
33dd0 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74   modify the cont
33de0 65 6e 74 73 20 6f 66 20 74 68 65 20 42 4c 4f 42  ents of the BLOB
33df0 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70  ; it is.** not p
33e00 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65  ossible to incre
33e10 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ase the size of 
33e20 61 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 68 69  a BLOB using thi
33e30 73 20 41 50 49 2e 0a 2a 2a 20 49 66 20 6f 66 66  s API..** If off
33e40 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c  set iOffset is l
33e50 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73  ess than N bytes
33e60 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66   from the end of
33e70 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53   the BLOB,.** [S
33e80 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
33e90 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
33ea0 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e  data is written.
33eb0 20 20 49 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73    If N is.** les
33ec0 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c  s than zero [SQL
33ed0 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
33ee0 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
33ef0 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a  ta is written..*
33f00 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68  * The size of th
33f10 65 20 42 4c 4f 42 20 28 61 6e 64 20 68 65 6e 63  e BLOB (and henc
33f20 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61  e the maximum va
33f30 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74  lue of N+iOffset
33f40 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  ).** can be dete
33f50 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  rmined using the
33f60 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62   [sqlite3_blob_b
33f70 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  ytes()] interfac
33f80 65 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65  e..**.** An atte
33f90 6d 70 74 20 74 6f 20 77 72 69 74 65 20 74 6f 20  mpt to write to 
33fa0 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42  an expired [BLOB
33fb0 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77   handle] fails w
33fc0 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  ith an.** error 
33fd0 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
33fe0 41 42 4f 52 54 5d 2e 20 20 57 72 69 74 65 73 20  ABORT].  Writes 
33ff0 74 6f 20 74 68 65 20 42 4c 4f 42 20 74 68 61 74  to the BLOB that
34000 20 6f 63 63 75 72 72 65 64 0a 2a 2a 20 62 65 66   occurred.** bef
34010 6f 72 65 20 74 68 65 20 5b 42 4c 4f 42 20 68 61  ore the [BLOB ha
34020 6e 64 6c 65 5d 20 65 78 70 69 72 65 64 20 61 72  ndle] expired ar
34030 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63  e not rolled bac
34040 6b 20 62 79 20 74 68 65 0a 2a 2a 20 65 78 70 69  k by the.** expi
34050 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 68 61  ration of the ha
34060 6e 64 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66 20  ndle, though of 
34070 63 6f 75 72 73 65 20 74 68 6f 73 65 20 63 68 61  course those cha
34080 6e 67 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61  nges might.** ha
34090 76 65 20 62 65 65 6e 20 6f 76 65 72 77 72 69 74  ve been overwrit
340a0 74 65 6e 20 62 79 20 74 68 65 20 73 74 61 74 65  ten by the state
340b0 6d 65 6e 74 20 74 68 61 74 20 65 78 70 69 72 65  ment that expire
340c0 64 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  d the BLOB handl
340d0 65 0a 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65 72  e.** or by other
340e0 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 73 74 61   independent sta
340f0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4f  tements..**.** O
34100 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54  n success, SQLIT
34110 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
34120 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20  ..** Otherwise, 
34130 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  an  [error code]
34140 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64   or an [extended
34150 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
34160 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
34170 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  This routine onl
34180 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c  y works on a [BL
34190 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68  OB handle] which
341a0 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65   has been create
341b0 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20  d.** by a prior 
341c0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
341d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
341e0 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69  _open()] and whi
341f0 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65  ch has not.** be
34200 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71  en closed by [sq
34210 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
34220 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e  ()].  Passing an
34230 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20  y other pointer 
34240 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f  in.** to this ro
34250 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e  utine results in
34260 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
34270 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
34280 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ble behavior..**
34290 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
342a0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
342b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ()]..**.** Requi
342c0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37  rements:.** [H17
342d0 38 37 33 5d 20 5b 48 31 37 38 37 34 5d 20 5b 48  873] [H17874] [H
342e0 31 37 38 37 35 5d 20 5b 48 31 37 38 37 36 5d 20  17875] [H17876] 
342f0 5b 48 31 37 38 37 37 5d 20 5b 48 31 37 38 37 39  [H17877] [H17879
34300 5d 20 5b 48 31 37 38 38 32 5d 20 5b 48 31 37 38  ] [H17882] [H178
34310 38 35 5d 0a 2a 2a 20 5b 48 31 37 38 38 38 5d 0a  85].** [H17888].
34320 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
34330 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65  lob_write(sqlite
34340 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20  3_blob *, const 
34350 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20  void *z, int n, 
34360 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f  int iOffset);../
34370 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
34380 69 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74  irtual File Syst
34390 65 6d 20 4f 62 6a 65 63 74 73 20 7b 48 31 31 32  em Objects {H112
343a0 30 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a  00} <S20100>.**.
343b0 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69 6c  ** A virtual fil
343c0 65 73 79 73 74 65 6d 20 28 56 46 53 29 20 69 73  esystem (VFS) is
343d0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
343e0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74  ] object.** that
343f0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f 20   SQLite uses to 
34400 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74 68  interact.** with
34410 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
34420 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
34430 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74 65 20 62  .  Most SQLite b
34440 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74 68 20  uilds come with 
34450 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66 61  a.** single defa
34460 75 6c 74 20 56 46 53 20 74 68 61 74 20 69 73 20  ult VFS that is 
34470 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
34480 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65  the host compute
34490 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20  r..** New VFSes 
344a0 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
344b0 64 20 61 6e 64 20 65 78 69 73 74 69 6e 67 20 56  d and existing V
344c0 46 53 65 73 20 63 61 6e 20 62 65 20 75 6e 72 65  FSes can be unre
344d0 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65  gistered..** The
344e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72   following inter
344f0 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
34500 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
34510 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
34520 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
34530 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
34540 61 20 56 46 53 20 67 69 76 65 6e 20 69 74 73 20  a VFS given its 
34550 6e 61 6d 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61  name..** Names a
34560 72 65 20 63 61 73 65 20 73 65 6e 73 69 74 69 76  re case sensitiv
34570 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20  e..** Names are 
34580 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
34590 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
345a0 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f  * If there is no
345b0 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20 70   match, a NULL p
345c0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
345d0 65 64 2e 0a 2a 2a 20 49 66 20 7a 56 66 73 4e 61  ed..** If zVfsNa
345e0 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  me is NULL then 
345f0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
34600 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
34610 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 61 72 65  ** New VFSes are
34620 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
34630 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67   sqlite3_vfs_reg
34640 69 73 74 65 72 28 29 2e 0a 2a 2a 20 45 61 63 68  ister()..** Each
34650 20 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73   new VFS becomes
34660 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
34670 20 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74   if the makeDflt
34680 20 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a   flag is set..**
34690 20 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 61   The same VFS ca
346a0 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
346b0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77  multiple times w
346c0 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a  ithout injury..*
346d0 2a 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69  * To make an exi
346e0 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74  sting VFS into t
346f0 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20  he default VFS, 
34700 72 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69  register it agai
34710 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61  n.** with the ma
34720 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e  keDflt flag set.
34730 20 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 65    If two differe
34740 6e 74 20 56 46 53 65 73 20 77 69 74 68 20 74 68  nt VFSes with th
34750 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61  e.** same name a
34760 72 65 20 72 65 67 69 73 74 65 72 65 64 2c 20 74  re registered, t
34770 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
34780 6e 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a  ndefined.  If a.
34790 2a 2a 20 56 46 53 20 69 73 20 72 65 67 69 73 74  ** VFS is regist
347a0 65 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65  ered with a name
347b0 20 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72   that is NULL or
347c0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
347d0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ,.** then the be
347e0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
347f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 55 6e 72 65 67  ned..**.** Unreg
34800 69 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68  ister a VFS with
34810 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
34820 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e  _unregister() in
34830 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 66 20 74  terface..** If t
34840 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
34850 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20  s unregistered, 
34860 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20 63  another VFS is c
34870 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20  hosen as.** the 
34880 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68  default.  The ch
34890 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77  oice for the new
348a0 20 56 46 53 20 69 73 20 61 72 62 69 74 72 61 72   VFS is arbitrar
348b0 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  y..**.** Require
348c0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 32 30  ments:.** [H1120
348d0 33 5d 20 5b 48 31 31 32 30 36 5d 20 5b 48 31 31  3] [H11206] [H11
348e0 32 30 39 5d 20 5b 48 31 31 32 31 32 5d 20 5b 48  209] [H11212] [H
348f0 31 31 32 31 35 5d 20 5b 48 31 31 32 31 38 5d 0a  11215] [H11218].
34900 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  */.sqlite3_vfs *
34910 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
34920 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66  (const char *zVf
34930 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69  sName);.int sqli
34940 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
34950 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
34960 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e  nt makeDflt);.in
34970 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e  t sqlite3_vfs_un
34980 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33  register(sqlite3
34990 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _vfs*);../*.** C
349a0 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73  API3REF: Mutexes
349b0 20 7b 48 31 37 30 30 30 7d 20 3c 53 32 30 30 30   {H17000} <S2000
349c0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  0>.**.** The SQL
349d0 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
349e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
349f0 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68   thread.** synch
34a00 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68 6f 75  ronization. Thou
34a10 67 68 20 74 68 65 79 20 61 72 65 20 69 6e 74 65  gh they are inte
34a20 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61  nded for interna
34a30 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69  l.** use by SQLi
34a40 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69  te, code that li
34a50 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69  nks against SQLi
34a60 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74  te is.** permitt
34a70 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66  ed to use any of
34a80 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
34a90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
34aa0 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f  e source code co
34ab0 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20  ntains multiple 
34ac0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
34ad0 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65  ** of these mute
34ae0 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20  x routines.  An 
34af0 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c  appropriate impl
34b00 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
34b10 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61   selected automa
34b20 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69  tically at compi
34b30 6c 65 2d 74 69 6d 65 2e 20 20 54 68 65 20 66 6f  le-time.  The fo
34b40 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65  llowing.** imple
34b50 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 61  mentations are a
34b60 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
34b70 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a  SQLite core:.**.
34b80 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
34b90 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f    SQLITE_MUTEX_O
34ba0 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  S2.** <li>   SQL
34bb0 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41  ITE_MUTEX_PTHREA
34bc0 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49  D.** <li>   SQLI
34bd0 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a 20  TE_MUTEX_W32.** 
34be0 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
34bf0 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c  TEX_NOOP.** </ul
34c00 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
34c10 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d  TE_MUTEX_NOOP im
34c20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
34c30 61 20 73 65 74 20 6f 66 20 72 6f 75 74 69 6e 65  a set of routine
34c40 73 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  s.** that does n
34c50 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61  o real locking a
34c60 6e 64 20 69 73 20 61 70 70 72 6f 70 72 69 61 74  nd is appropriat
34c70 65 20 66 6f 72 20 75 73 65 20 69 6e 0a 2a 2a 20  e for use in.** 
34c80 61 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  a single-threade
34c90 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  d application.  
34ca0 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  The SQLITE_MUTEX
34cb0 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f  _OS2,.** SQLITE_
34cc0 4d 55 54 45 58 5f 50 54 48 52 45 41 44 2c 20 61  MUTEX_PTHREAD, a
34cd0 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  nd SQLITE_MUTEX_
34ce0 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  W32 implementati
34cf0 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f  ons.** are appro
34d00 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 6f  priate for use o
34d10 6e 20 4f 53 2f 32 2c 20 55 6e 69 78 2c 20 61 6e  n OS/2, Unix, an
34d20 64 20 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a  d Windows..**.**
34d30 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
34d40 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
34d50 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50  SQLITE_MUTEX_APP
34d60 44 45 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72  DEF preprocessor
34d70 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  .** macro define
34d80 64 20 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54  d (with "-DSQLIT
34d90 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31  E_MUTEX_APPDEF=1
34da0 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65  "), then no mute
34db0 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  x.** implementat
34dc0 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20  ion is included 
34dd0 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
34de0 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 74  . In this case t
34df0 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
34e00 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
34e10 63 75 73 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70  custom mutex imp
34e20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e  lementation usin
34e30 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
34e40 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f  _CONFIG_MUTEX] o
34e50 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c  ption of the sql
34e60 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 66 75  ite3_config() fu
34e70 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65  nction.** before
34e80 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
34e90 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 6f 72  _initialize() or
34ea0 20 61 6e 79 20 6f 74 68 65 72 20 70 75 62 6c 69   any other publi
34eb0 63 20 73 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75  c sqlite3_.** fu
34ec0 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c  nction that call
34ed0 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
34ee0 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48  lize()..**.** {H
34ef0 31 37 30 31 31 7d 20 54 68 65 20 73 71 6c 69 74  17011} The sqlit
34f00 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
34f10 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61 74   routine allocat
34f20 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 65  es a new.** mute
34f30 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  x and returns a 
34f40 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 7b  pointer to it. {
34f50 48 31 37 30 31 32 7d 20 49 66 20 69 74 20 72 65  H17012} If it re
34f60 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68  turns NULL.** th
34f70 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  at means that a 
34f80 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20  mutex could not 
34f90 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 48  be allocated. {H
34fa0 31 37 30 31 33 7d 20 53 51 4c 69 74 65 0a 2a 2a  17013} SQLite.**
34fb0 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73   will unwind its
34fc0 20 73 74 61 63 6b 20 61 6e 64 20 72 65 74 75 72   stack and retur
34fd0 6e 20 61 6e 20 65 72 72 6f 72 2e 20 7b 48 31 37  n an error. {H17
34fe0 30 31 34 7d 20 54 68 65 20 61 72 67 75 6d 65 6e  014} The argumen
34ff0 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
35000 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73  mutex_alloc() is
35010 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
35020 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a  teger constants:
35030 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
35040 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
35050 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20  X_FAST.** <li>  
35060 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
35070 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  URSIVE.** <li>  
35080 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
35090 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c  TIC_MASTER.** <l
350a0 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
350b0 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c  _STATIC_MEM.** <
350c0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
350d0 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a  X_STATIC_MEM2.**
350e0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
350f0 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a  TEX_STATIC_PRNG.
35100 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
35110 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
35120 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
35130 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
35140 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  U2.** </ul>.**.*
35150 2a 20 7b 48 31 37 30 31 35 7d 20 54 68 65 20 66  * {H17015} The f
35160 69 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e  irst two constan
35170 74 73 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  ts cause sqlite3
35180 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74  _mutex_alloc() t
35190 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65  o create.** a ne
351a0 77 20 6d 75 74 65 78 2e 20 20 54 68 65 20 6e 65  w mutex.  The ne
351b0 77 20 6d 75 74 65 78 20 69 73 20 72 65 63 75 72  w mutex is recur
351c0 73 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45  sive when SQLITE
351d0 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
351e0 0a 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74 20  .** is used but 
351f0 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20  not necessarily 
35200 73 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d  so when SQLITE_M
35210 55 54 45 58 5f 46 41 53 54 20 69 73 20 75 73 65  UTEX_FAST is use
35220 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 65 20  d. {END}.** The 
35230 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
35240 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
35250 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73  ed to make a dis
35260 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
35270 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  een SQLITE_MUTEX
35280 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 20 53  _RECURSIVE and S
35290 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
352a0 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   if it does.** n
352b0 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 7b 48 31  ot want to.  {H1
352c0 37 30 31 36 7d 20 42 75 74 20 53 51 4c 69 74 65  7016} But SQLite
352d0 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65   will only reque
352e0 73 74 20 61 20 72 65 63 75 72 73 69 76 65 20 6d  st a recursive m
352f0 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73  utex in.** cases
35300 20 77 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79   where it really
35310 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 7b 45 4e   needs one.  {EN
35320 44 7d 20 49 66 20 61 20 66 61 73 74 65 72 20 6e  D} If a faster n
35330 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d 75 74  on-recursive mut
35340 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ex.** implementa
35350 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
35360 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 6c  e on the host pl
35370 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65  atform, the mute
35380 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d  x subsystem.** m
35390 69 67 68 74 20 72 65 74 75 72 6e 20 73 75 63 68  ight return such
353a0 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65 73 70   a mutex in resp
353b0 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d  onse to SQLITE_M
353c0 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a  UTEX_FAST..**.**
353d0 20 7b 48 31 37 30 31 37 7d 20 54 68 65 20 6f 74   {H17017} The ot
353e0 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61  her allowed para
353f0 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65  meters to sqlite
35400 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
35410 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20 61  each return.** a
35420 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
35430 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e 67  atic preexisting
35440 20 6d 75 74 65 78 2e 20 7b 45 4e 44 7d 20 20 53   mutex. {END}  S
35450 69 78 20 73 74 61 74 69 63 20 6d 75 74 65 78 65  ix static mutexe
35460 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79  s are.** used by
35470 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 65 72   the current ver
35480 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20  sion of SQLite. 
35490 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
354a0 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61   of SQLite.** ma
354b0 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
354c0 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e   static mutexes.
354d0 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 73    Static mutexes
354e0 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61   are for interna
354f0 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69  l.** use by SQLi
35500 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63  te only.  Applic
35510 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
35520 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73  SQLite mutexes s
35530 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c  hould.** use onl
35540 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75  y the dynamic mu
35550 74 65 78 65 73 20 72 65 74 75 72 6e 65 64 20 62  texes returned b
35560 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  y SQLITE_MUTEX_F
35570 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45  AST or.** SQLITE
35580 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
35590 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 38 7d  ..**.** {H17018}
355a0 20 4e 6f 74 65 20 74 68 61 74 20 69 66 20 6f 6e   Note that if on
355b0 65 20 6f 66 20 74 68 65 20 64 79 6e 61 6d 69 63  e of the dynamic
355c0 20 6d 75 74 65 78 20 70 61 72 61 6d 65 74 65 72   mutex parameter
355d0 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  s (SQLITE_MUTEX_
355e0 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54  FAST.** or SQLIT
355f0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
35600 45 29 20 69 73 20 75 73 65 64 20 74 68 65 6e 20  E) is used then 
35610 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
35620 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  loc().** returns
35630 20 61 20 64 69 66 66 65 72 65 6e 74 20 6d 75 74   a different mut
35640 65 78 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c  ex on every call
35650 2e 20 20 7b 48 31 37 30 33 34 7d 20 42 75 74 20  .  {H17034} But 
35660 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a  for the static.*
35670 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74  * mutex types, t
35680 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73  he same mutex is
35690 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65   returned on eve
356a0 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73  ry call that has
356b0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70  .** the same typ
356c0 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  e number..**.** 
356d0 7b 48 31 37 30 31 39 7d 20 54 68 65 20 73 71 6c  {H17019} The sql
356e0 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28  ite3_mutex_free(
356f0 29 20 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f  ) routine deallo
35700 63 61 74 65 73 20 61 20 70 72 65 76 69 6f 75 73  cates a previous
35710 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20  ly.** allocated 
35720 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 7b  dynamic mutex. {
35730 48 31 37 30 32 30 7d 20 53 51 4c 69 74 65 20 69  H17020} SQLite i
35740 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61  s careful to dea
35750 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a  llocate every.**
35760 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74   dynamic mutex t
35770 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73  hat it allocates
35780 2e 20 7b 41 31 37 30 32 31 7d 20 54 68 65 20 64  . {A17021} The d
35790 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 6d  ynamic mutexes m
357a0 75 73 74 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a  ust not be in.**
357b0 20 75 73 65 20 77 68 65 6e 20 74 68 65 79 20 61   use when they a
357c0 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20  re deallocated. 
357d0 7b 41 31 37 30 32 32 7d 20 41 74 74 65 6d 70 74  {A17022} Attempt
357e0 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74  ing to deallocat
357f0 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75  e a static.** mu
35800 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20 75  tex results in u
35810 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
35820 72 2e 20 7b 48 31 37 30 32 33 7d 20 53 51 4c 69  r. {H17023} SQLi
35830 74 65 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63  te never dealloc
35840 61 74 65 73 0a 2a 2a 20 61 20 73 74 61 74 69 63  ates.** a static
35850 20 6d 75 74 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a   mutex. {END}.**
35860 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
35870 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 61 6e  mutex_enter() an
35880 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
35890 74 72 79 28 29 20 72 6f 75 74 69 6e 65 73 20 61  try() routines a
358a0 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74  ttempt.** to ent
358b0 65 72 20 61 20 6d 75 74 65 78 2e 20 7b 48 31 37  er a mutex. {H17
358c0 30 32 34 7d 20 49 66 20 61 6e 6f 74 68 65 72 20  024} If another 
358d0 74 68 72 65 61 64 20 69 73 20 61 6c 72 65 61 64  thread is alread
358e0 79 20 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74  y within the mut
358f0 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ex,.** sqlite3_m
35900 75 74 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c  utex_enter() wil
35910 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69  l block and sqli
35920 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
35930 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53  will return.** S
35940 51 4c 49 54 45 5f 42 55 53 59 2e 20 7b 48 31 37  QLITE_BUSY. {H17
35950 30 32 35 7d 20 20 54 68 65 20 73 71 6c 69 74 65  025}  The sqlite
35960 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 69 6e  3_mutex_try() in
35970 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35980 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75  [SQLITE_OK].** u
35990 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c 20 65  pon successful e
359a0 6e 74 72 79 2e 20 20 7b 48 31 37 30 32 36 7d 20  ntry.  {H17026} 
359b0 4d 75 74 65 78 65 73 20 63 72 65 61 74 65 64 20  Mutexes created 
359c0 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f  using.** SQLITE_
359d0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20  MUTEX_RECURSIVE 
359e0 63 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d  can be entered m
359f0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79  ultiple times by
35a00 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
35a10 2e 0a 2a 2a 20 7b 48 31 37 30 32 37 7d 20 49 6e  ..** {H17027} In
35a20 20 73 75 63 68 20 63 61 73 65 73 20 74 68 65 2c   such cases the,
35a30 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 62  .** mutex must b
35a40 65 20 65 78 69 74 65 64 20 61 6e 20 65 71 75 61  e exited an equa
35a50 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  l number of time
35a60 73 20 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 72  s before another
35a70 20 74 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65   thread.** can e
35a80 6e 74 65 72 2e 20 20 7b 41 31 37 30 32 38 7d 20  nter.  {A17028} 
35a90 49 66 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  If the same thre
35aa0 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74 65  ad tries to ente
35ab0 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b  r any other.** k
35ac0 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72  ind of mutex mor
35ad0 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65  e than once, the
35ae0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
35af0 65 66 69 6e 65 64 2e 0a 2a 2a 20 7b 48 31 37 30  efined..** {H170
35b00 32 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  29} SQLite will 
35b10 6e 65 76 65 72 20 65 78 68 69 62 69 74 0a 2a 2a  never exhibit.**
35b20 20 73 75 63 68 20 62 65 68 61 76 69 6f 72 20 69   such behavior i
35b30 6e 20 69 74 73 20 6f 77 6e 20 75 73 65 20 6f 66  n its own use of
35b40 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20   mutexes..**.** 
35b50 53 6f 6d 65 20 73 79 73 74 65 6d 73 20 28 66 6f  Some systems (fo
35b60 72 20 65 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f  r example, Windo
35b70 77 73 20 39 35 29 20 64 6f 20 6e 6f 74 20 73 75  ws 95) do not su
35b80 70 70 6f 72 74 20 74 68 65 20 6f 70 65 72 61 74  pport the operat
35b90 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
35ba0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 75  ed by sqlite3_mu
35bb0 74 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74  tex_try().  On t
35bc0 68 6f 73 65 20 73 79 73 74 65 6d 73 2c 20 73 71  hose systems, sq
35bd0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
35be0 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73  ).** will always
35bf0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42   return SQLITE_B
35c00 55 53 59 2e 20 20 7b 48 31 37 30 33 30 7d 20 54  USY.  {H17030} T
35c10 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f  he SQLite core o
35c20 6e 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a  nly ever uses.**
35c30 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
35c40 72 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d  ry() as an optim
35c50 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20  ization so this 
35c60 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 62 65  is acceptable be
35c70 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  havior..**.** {H
35c80 31 37 30 33 31 7d 20 54 68 65 20 73 71 6c 69 74  17031} The sqlit
35c90 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29  e3_mutex_leave()
35ca0 20 72 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61   routine exits a
35cb0 20 6d 75 74 65 78 20 74 68 61 74 20 77 61 73 0a   mutex that was.
35cc0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e  ** previously en
35cd0 74 65 72 65 64 20 62 79 20 74 68 65 20 73 61 6d  tered by the sam
35ce0 65 20 74 68 72 65 61 64 2e 20 20 7b 41 31 37 30  e thread.  {A170
35cf0 33 32 7d 20 54 68 65 20 62 65 68 61 76 69 6f 72  32} The behavior
35d00 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
35d10 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 73   if the mutex is
35d20 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 65   not currently e
35d30 6e 74 65 72 65 64 20 62 79 20 74 68 65 0a 2a 2a  ntered by the.**
35d40 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
35d50 6f 72 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  or is not curren
35d60 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20  tly allocated.  
35d70 7b 48 31 37 30 33 33 7d 20 53 51 4c 69 74 65 20  {H17033} SQLite 
35d80 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f  will.** never do
35d90 20 65 69 74 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a   either. {END}.*
35da0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 61 72 67 75  *.** If the argu
35db0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
35dc0 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 2c 20 73  mutex_enter(), s
35dd0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
35de0 28 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  (), or.** sqlite
35df0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20  3_mutex_leave() 
35e00 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
35e10 72 2c 20 74 68 65 6e 20 61 6c 6c 20 74 68 72 65  r, then all thre
35e20 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65  e routines.** be
35e30 68 61 76 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a  have as no-ops..
35e40 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
35e50 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68  [sqlite3_mutex_h
35e60 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  eld()] and [sqli
35e70 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
35e80 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  d()]..*/.sqlite3
35e90 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f  _mutex *sqlite3_
35ea0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29  mutex_alloc(int)
35eb0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d  ;.void sqlite3_m
35ec0 75 74 65 78 5f 66 72 65 65 28 73 71 6c 69 74 65  utex_free(sqlite
35ed0 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20  3_mutex*);.void 
35ee0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
35ef0 74 65 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ter(sqlite3_mute
35f00 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  x*);.int sqlite3
35f10 5f 6d 75 74 65 78 5f 74 72 79 28 73 71 6c 69 74  _mutex_try(sqlit
35f20 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64  e3_mutex*);.void
35f30 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c   sqlite3_mutex_l
35f40 65 61 76 65 28 73 71 6c 69 74 65 33 5f 6d 75 74  eave(sqlite3_mut
35f50 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ex*);../*.** CAP
35f60 49 33 52 45 46 3a 20 4d 75 74 65 78 20 4d 65 74  I3REF: Mutex Met
35f70 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 37  hods Object {H17
35f80 31 32 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a  120} <S20130>.**
35f90 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
35fa0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
35fb0 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
35fc0 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 6c 6f  e defines the lo
35fd0 77 2d 6c 65 76 65 6c 20 72 6f 75 74 69 6e 65 73  w-level routines
35fe0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f  .** used to allo
35ff0 63 61 74 65 20 61 6e 64 20 75 73 65 20 6d 75 74  cate and use mut
36000 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61  exes..**.** Usua
36010 6c 6c 79 2c 20 74 68 65 20 64 65 66 61 75 6c 74  lly, the default
36020 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
36030 61 74 69 6f 6e 73 20 70 72 6f 76 69 64 65 64 20  ations provided 
36040 62 79 20 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a  by SQLite are.**
36050 20 73 75 66 66 69 63 69 65 6e 74 2c 20 68 6f 77   sufficient, how
36060 65 76 65 72 20 74 68 65 20 75 73 65 72 20 68 61  ever the user ha
36070 73 20 74 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20  s the option of 
36080 73 75 62 73 74 69 74 75 74 69 6e 67 20 61 20 63  substituting a c
36090 75 73 74 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ustom.** impleme
360a0 6e 74 61 74 69 6f 6e 20 66 6f 72 20 73 70 65 63  ntation for spec
360b0 69 61 6c 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65  ialized deployme
360c0 6e 74 73 20 6f 72 20 73 79 73 74 65 6d 73 20 66  nts or systems f
360d0 6f 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 0a  or which SQLite.
360e0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76  ** does not prov
360f0 69 64 65 20 61 20 73 75 69 74 61 62 6c 65 20 69  ide a suitable i
36100 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49  mplementation. I
36110 6e 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65  n this case, the
36120 20 75 73 65 72 0a 2a 2a 20 63 72 65 61 74 65 73   user.** creates
36130 20 61 6e 64 20 70 6f 70 75 6c 61 74 65 73 20 61   and populates a
36140 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
36150 69 73 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  is structure to 
36160 70 61 73 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  pass.** to sqlit
36170 65 33 5f 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e  e3_config() alon
36180 67 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  g with the [SQLI
36190 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
361a0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69   option..** Addi
361b0 74 69 6f 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73  tionally, an ins
361c0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74  tance of this st
361d0 72 75 63 74 75 72 65 20 63 61 6e 20 62 65 20 75  ructure can be u
361e0 73 65 64 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74  sed as an.** out
361f0 70 75 74 20 76 61 72 69 61 62 6c 65 20 77 68 65  put variable whe
36200 6e 20 71 75 65 72 79 69 6e 67 20 74 68 65 20 73  n querying the s
36210 79 73 74 65 6d 20 66 6f 72 20 74 68 65 20 63 75  ystem for the cu
36220 72 72 65 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69  rrent mutex.** i
36230 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75  mplementation, u
36240 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
36250 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
36260 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ] option..**.** 
36270 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d  The xMutexInit m
36280 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79  ethod defined by
36290 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
362a0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a  is invoked as.**
362b0 20 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20   part of system 
362c0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62  initialization b
362d0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
362e0 69 74 69 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  itialize() funct
362f0 69 6f 6e 2e 0a 2a 2a 20 7b 48 31 37 30 30 31 7d  ion..** {H17001}
36300 20 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20   The xMutexInit 
36310 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 62 65  routine shall be
36320 20 63 61 6c 6c 65 64 20 62 79 20 53 51 4c 69 74   called by SQLit
36330 65 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 0a  e once for each.
36340 2a 2a 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  ** effective cal
36350 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e  l to [sqlite3_in
36360 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a  itialize()]..**.
36370 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64  ** The xMutexEnd
36380 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20   method defined 
36390 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72  by this structur
363a0 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a  e is invoked as.
363b0 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65  ** part of syste
363c0 6d 20 73 68 75 74 64 6f 77 6e 20 62 79 20 74 68  m shutdown by th
363d0 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
363e0 77 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e 20 54  wn() function. T
363f0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
36400 74 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d 65 74  tion of this met
36410 68 6f 64 20 69 73 20 65 78 70 65 63 74 65 64 20  hod is expected 
36420 74 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c 20 6f  to release all o
36430 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 65  utstanding.** re
36440 73 6f 75 72 63 65 73 20 6f 62 74 61 69 6e 65 64  sources obtained
36450 20 62 79 20 74 68 65 20 6d 75 74 65 78 20 6d 65   by the mutex me
36460 74 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e 74 61  thods implementa
36470 74 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c 6c 79  tion, especially
36480 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61 69 6e  .** those obtain
36490 65 64 20 62 79 20 74 68 65 20 78 4d 75 74 65 78  ed by the xMutex
364a0 49 6e 69 74 20 6d 65 74 68 6f 64 2e 20 7b 48 31  Init method. {H1
364b0 37 30 30 33 7d 20 54 68 65 20 78 4d 75 74 65 78  7003} The xMutex
364c0 45 6e 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  End().** interfa
364d0 63 65 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f  ce shall be invo
364e0 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  ked once for eac
364f0 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
36500 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
36510 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  **.** The remain
36520 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 6f 64  ing seven method
36530 73 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69  s defined by thi
36540 73 20 73 74 72 75 63 74 75 72 65 20 28 78 4d 75  s structure (xMu
36550 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75  texAlloc,.** xMu
36560 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65 78 45  texFree, xMutexE
36570 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72 79 2c  nter, xMutexTry,
36580 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 78 4d   xMutexLeave, xM
36590 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20  utexHeld and.** 
365a0 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 20 69  xMutexNotheld) i
365b0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c  mplement the fol
365c0 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65  lowing interface
365d0 73 20 28 72 65 73 70 65 63 74 69 76 65 6c 79 29  s (respectively)
365e0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
365f0 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
36600 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20  _mutex_alloc()] 
36610 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
36620 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
36630 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  free()] </li>.**
36640 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
36650 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 5d  3_mutex_enter()]
36660 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
36670 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
36680 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  _try()] </li>.**
36690 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
366a0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 5d  3_mutex_leave()]
366b0 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
366c0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
366d0 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  _held()] </li>.*
366e0 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
366f0 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
36700 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  ()] </li>.** </u
36710 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c  l>.**.** The onl
36720 79 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  y difference is 
36730 74 68 61 74 20 74 68 65 20 70 75 62 6c 69 63 20  that the public 
36740 73 71 6c 69 74 65 33 5f 58 58 58 20 66 75 6e 63  sqlite3_XXX func
36750 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61 74 65 64  tions enumerated
36760 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c 65 6e 74  .** above silent
36770 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e  ly ignore any in
36780 76 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 70  vocations that p
36790 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ass a NULL point
367a0 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  er instead.** of
367b0 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68   a valid mutex h
367c0 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65  andle. The imple
367d0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
367e0 65 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65  e methods define
367f0 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 73 74 72  d.** by this str
36800 75 63 74 75 72 65 20 61 72 65 20 6e 6f 74 20 72  ucture are not r
36810 65 71 75 69 72 65 64 20 74 6f 20 68 61 6e 64 6c  equired to handl
36820 65 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65  e this case, the
36830 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70   results.** of p
36840 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
36850 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
36860 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68   a valid mutex h
36870 61 6e 64 6c 65 20 61 72 65 20 75 6e 64 65 66 69  andle are undefi
36880 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20  ned.** (i.e. it 
36890 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 74 6f  is acceptable to
368a0 20 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c   provide an impl
368b0 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
368c0 73 65 67 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20  segfaults if.** 
368d0 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20 4e  it is passed a N
368e0 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2a  ULL pointer)..**
368f0 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 49 6e  .** The xMutexIn
36900 69 74 28 29 20 6d 65 74 68 6f 64 20 6d 75 73 74  it() method must
36910 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
36920 20 49 74 20 6d 75 73 74 20 62 65 20 68 61 72 6d   It must be harm
36930 6c 65 73 73 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  less to.** invok
36940 65 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d  e xMutexInit() m
36950 75 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74  utiple times wit
36960 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
36970 63 65 73 73 20 61 6e 64 20 77 69 74 68 6f 75 74  cess and without
36980 0a 2a 2a 20 69 6e 74 65 72 76 65 6e 69 6e 67 20  .** intervening 
36990 63 61 6c 6c 73 20 74 6f 20 78 4d 75 74 65 78 45  calls to xMutexE
369a0 6e 64 28 29 2e 20 20 53 65 63 6f 6e 64 20 61 6e  nd().  Second an
369b0 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
369c0 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75 74 65 78 49  ls to.** xMutexI
369d0 6e 69 74 28 29 20 6d 75 73 74 20 62 65 20 6e 6f  nit() must be no
369e0 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 78 4d 75 74  -ops..**.** xMut
369f0 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 6e 6f  exInit() must no
36a00 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 65 6d  t use SQLite mem
36a10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28  ory allocation (
36a20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
36a30 29 5d 0a 2a 2a 20 61 6e 64 20 69 74 73 20 61 73  )].** and its as
36a40 73 6f 63 69 61 74 65 73 29 2e 20 20 53 69 6d 69  sociates).  Simi
36a50 6c 61 72 6c 79 2c 20 78 4d 75 74 65 78 41 6c 6c  larly, xMutexAll
36a60 6f 63 28 29 20 6d 75 73 74 20 6e 6f 74 20 75 73  oc() must not us
36a70 65 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 0a  e SQLite memory.
36a80 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ** allocation fo
36a90 72 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78  r a static mutex
36aa0 2e 20 20 48 6f 77 65 76 65 72 20 78 4d 75 74 65  .  However xMute
36ab0 78 41 6c 6c 6f 63 28 29 20 6d 61 79 20 75 73 65  xAlloc() may use
36ac0 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 65 6d 6f 72   SQLite.** memor
36ad0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
36ae0 20 61 20 66 61 73 74 20 6f 72 20 72 65 63 75 72   a fast or recur
36af0 73 69 76 65 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a  sive mutex..**.*
36b00 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  * SQLite will in
36b10 76 6f 6b 65 20 74 68 65 20 78 4d 75 74 65 78 45  voke the xMutexE
36b20 6e 64 28 29 20 6d 65 74 68 6f 64 20 77 68 65 6e  nd() method when
36b30 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
36b40 77 6e 28 29 5d 20 69 73 0a 2a 2a 20 63 61 6c 6c  wn()] is.** call
36b50 65 64 2c 20 62 75 74 20 6f 6e 6c 79 20 69 66 20  ed, but only if 
36b60 74 68 65 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  the prior call t
36b70 6f 20 78 4d 75 74 65 78 49 6e 69 74 20 72 65 74  o xMutexInit ret
36b80 75 72 6e 65 64 20 53 51 4c 49 54 45 5f 4f 4b 2e  urned SQLITE_OK.
36b90 0a 2a 2a 20 49 66 20 78 4d 75 74 65 78 49 6e 69  .** If xMutexIni
36ba0 74 20 66 61 69 6c 73 20 69 6e 20 61 6e 79 20 77  t fails in any w
36bb0 61 79 2c 20 69 74 20 69 73 20 65 78 70 65 63 74  ay, it is expect
36bc0 65 64 20 74 6f 20 63 6c 65 61 6e 20 75 70 20 61  ed to clean up a
36bd0 66 74 65 72 20 69 74 73 65 6c 66 0a 2a 2a 20 70  fter itself.** p
36be0 72 69 6f 72 20 74 6f 20 72 65 74 75 72 6e 69 6e  rior to returnin
36bf0 67 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  g..*/.typedef st
36c00 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
36c10 65 78 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  ex_methods sqlit
36c20 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
36c30 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
36c40 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 7b  _mutex_methods {
36c50 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 49  .  int (*xMutexI
36c60 6e 69 74 29 28 76 6f 69 64 29 3b 0a 20 20 69 6e  nit)(void);.  in
36c70 74 20 28 2a 78 4d 75 74 65 78 45 6e 64 29 28 76  t (*xMutexEnd)(v
36c80 6f 69 64 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  oid);.  sqlite3_
36c90 6d 75 74 65 78 20 2a 28 2a 78 4d 75 74 65 78 41  mutex *(*xMutexA
36ca0 6c 6c 6f 63 29 28 69 6e 74 29 3b 0a 20 20 76 6f  lloc)(int);.  vo
36cb0 69 64 20 28 2a 78 4d 75 74 65 78 46 72 65 65 29  id (*xMutexFree)
36cc0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
36cd0 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74  );.  void (*xMut
36ce0 65 78 45 6e 74 65 72 29 28 73 71 6c 69 74 65 33  exEnter)(sqlite3
36cf0 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74  _mutex *);.  int
36d00 20 28 2a 78 4d 75 74 65 78 54 72 79 29 28 73 71   (*xMutexTry)(sq
36d10 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
36d20 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 4c    void (*xMutexL
36d30 65 61 76 65 29 28 73 71 6c 69 74 65 33 5f 6d 75  eave)(sqlite3_mu
36d40 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  tex *);.  int (*
36d50 78 4d 75 74 65 78 48 65 6c 64 29 28 73 71 6c 69  xMutexHeld)(sqli
36d60 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20  te3_mutex *);.  
36d70 69 6e 74 20 28 2a 78 4d 75 74 65 78 4e 6f 74 68  int (*xMutexNoth
36d80 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74  eld)(sqlite3_mut
36d90 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ex *);.};../*.**
36da0 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
36db0 20 56 65 72 69 66 69 63 61 74 69 6f 6e 20 52 6f   Verification Ro
36dc0 75 74 69 6e 65 73 20 7b 48 31 37 30 38 30 7d 20  utines {H17080} 
36dd0 3c 53 32 30 31 33 30 3e 20 3c 53 33 30 38 30 30  <S20130> <S30800
36de0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
36df0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
36e00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
36e10 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75  ex_notheld() rou
36e20 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74  tines.** are int
36e30 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
36e40 73 69 64 65 20 61 73 73 65 72 74 28 29 20 73 74  side assert() st
36e50 61 74 65 6d 65 6e 74 73 2e 20 7b 48 31 37 30 38  atements. {H1708
36e60 31 7d 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  1} The SQLite co
36e70 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73 65 73  re.** never uses
36e80 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
36e90 65 78 63 65 70 74 20 69 6e 73 69 64 65 20 61 6e  except inside an
36ea0 20 61 73 73 65 72 74 28 29 20 61 6e 64 20 61 70   assert() and ap
36eb0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 72  plications.** ar
36ec0 65 20 61 64 76 69 73 65 64 20 74 6f 20 66 6f 6c  e advised to fol
36ed0 6c 6f 77 20 74 68 65 20 6c 65 61 64 20 6f 66 20  low the lead of 
36ee0 74 68 65 20 63 6f 72 65 2e 20 20 7b 48 31 37 30  the core.  {H170
36ef0 38 32 7d 20 54 68 65 20 63 6f 72 65 20 6f 6e 6c  82} The core onl
36f00 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 69 6d  y.** provides im
36f10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
36f20 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
36f30 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
36f40 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  iled.** with the
36f50 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 66 6c   SQLITE_DEBUG fl
36f60 61 67 2e 20 20 7b 41 31 37 30 38 37 7d 20 45 78  ag.  {A17087} Ex
36f70 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70  ternal mutex imp
36f80 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20  lementations.** 
36f90 61 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65  are only require
36fa0 64 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65  d to provide the
36fb0 73 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53  se routines if S
36fc0 51 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a  QLITE_DEBUG is.*
36fd0 2a 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66  * defined and if
36fe0 20 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64   NDEBUG is not d
36ff0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  efined..**.** {H
37000 31 37 30 38 33 7d 20 54 68 65 73 65 20 72 6f 75  17083} These rou
37010 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 72 65 74  tines should ret
37020 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20  urn true if the 
37030 6d 75 74 65 78 20 69 6e 20 74 68 65 69 72 20 61  mutex in their a
37040 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 68 65  rgument.** is he
37050 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64 2c 20  ld or not held, 
37060 72 65 73 70 65 63 74 69 76 65 6c 79 2c 20 62 79  respectively, by
37070 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
37080 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 58 31 37 30  ead..**.** {X170
37090 38 34 7d 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  84} The implemen
370a0 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65  tation is not re
370b0 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64  quired to provid
370c0 65 64 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74  ed versions of t
370d0 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  hese.** routines
370e0 20 74 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77   that actually w
370f0 6f 72 6b 2e 20 49 66 20 74 68 65 20 69 6d 70 6c  ork. If the impl
37100 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20  ementation does 
37110 6e 6f 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b  not provide work
37120 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ing.** versions 
37130 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
37140 73 2c 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20  s, it should at 
37150 6c 65 61 73 74 20 70 72 6f 76 69 64 65 20 73 74  least provide st
37160 75 62 73 20 74 68 61 74 20 61 6c 77 61 79 73 0a  ubs that always.
37170 2a 2a 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  ** return true s
37180 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20  o that one does 
37190 6e 6f 74 20 67 65 74 20 73 70 75 72 69 6f 75 73  not get spurious
371a0 20 61 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75   assertion failu
371b0 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30  res..**.** {H170
371c0 38 35 7d 20 49 66 20 74 68 65 20 61 72 67 75 6d  85} If the argum
371d0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  ent to sqlite3_m
371e0 75 74 65 78 5f 68 65 6c 64 28 29 20 69 73 20 61  utex_held() is a
371f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
37200 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e  en.** the routin
37210 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
37220 31 2e 20 20 7b 45 4e 44 7d 20 54 68 69 73 20 73  1.  {END} This s
37230 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74  eems counter-int
37240 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20  uitive since.** 
37250 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65  clearly the mute
37260 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64  x cannot be held
37270 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20   if it does not 
37280 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a  exist.  But the.
37290 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68  ** the reason th
372a0 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74  e mutex does not
372b0 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75 73   exist is becaus
372c0 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e  e the build is n
372d0 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65  ot.** using mute
372e0 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20  xes.  And we do 
372f0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73 73  not want the ass
37300 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67  ert() containing
37310 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20   the.** call to 
37320 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
37330 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f  ld() to fail, so
37340 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75   a non-zero retu
37350 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70  rn is.** the app
37360 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20 74  ropriate thing t
37370 6f 20 64 6f 2e 20 20 7b 48 31 37 30 38 36 7d 20  o do.  {H17086} 
37380 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
37390 78 5f 6e 6f 74 68 65 6c 64 28 29 0a 2a 2a 20 69  x_notheld().** i
373a0 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20  nterface should 
373b0 61 6c 73 6f 20 72 65 74 75 72 6e 20 31 20 77 68  also return 1 wh
373c0 65 6e 20 67 69 76 65 6e 20 61 20 4e 55 4c 4c 20  en given a NULL 
373d0 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20  pointer..*/.int 
373e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
373f0 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ld(sqlite3_mutex
37400 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
37410 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 73 71  mutex_notheld(sq
37420 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a  lite3_mutex*);..
37430 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37440 4d 75 74 65 78 20 54 79 70 65 73 20 7b 48 31 37  Mutex Types {H17
37450 30 30 31 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 2a  001} <H17000>.**
37460 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
37470 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20  _mutex_alloc()] 
37480 69 6e 74 65 72 66 61 63 65 20 74 61 6b 65 73 20  interface takes 
37490 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
374a0 74 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 6f 6e  t.** which is on
374b0 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
374c0 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a  er constants..**
374d0 0a 2a 2a 20 54 68 65 20 73 65 74 20 6f 66 20 73  .** The set of s
374e0 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 6d 61  tatic mutexes ma
374f0 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e  y change from on
37500 65 20 53 51 4c 69 74 65 20 72 65 6c 65 61 73 65  e SQLite release
37510 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
37520 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
37530 68 61 74 20 6f 76 65 72 72 69 64 65 20 74 68 65  hat override the
37540 20 62 75 69 6c 74 2d 69 6e 20 6d 75 74 65 78 20   built-in mutex 
37550 6c 6f 67 69 63 20 6d 75 73 74 20 62 65 0a 2a 2a  logic must be.**
37560 20 70 72 65 70 61 72 65 64 20 74 6f 20 61 63 63   prepared to acc
37570 6f 6d 6d 6f 64 61 74 65 20 61 64 64 69 74 69 6f  ommodate additio
37580 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78  nal static mutex
37590 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  es..*/.#define S
375a0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
375b0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
375c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
375d0 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 20 20  TEX_RECURSIVE   
375e0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
375f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
37600 49 43 5f 4d 41 53 54 45 52 20 20 20 20 32 0a 23  IC_MASTER    2.#
37610 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
37620 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20  TEX_STATIC_MEM  
37630 20 20 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 74       3  /* sqlit
37640 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23  e3_malloc() */.#
37650 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
37660 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20  TEX_STATIC_MEM2 
37670 20 20 20 20 20 34 20 20 2f 2a 20 4e 4f 54 20 55       4  /* NOT U
37680 53 45 44 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  SED */.#define S
37690 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
376a0 49 43 5f 4f 50 45 4e 20 20 20 20 20 20 34 20 20  IC_OPEN      4  
376b0 2f 2a 20 73 71 6c 69 74 65 33 42 74 72 65 65 4f  /* sqlite3BtreeO
376c0 70 65 6e 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  pen() */.#define
376d0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
376e0 41 54 49 43 5f 50 52 4e 47 20 20 20 20 20 20 35  ATIC_PRNG      5
376f0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e    /* sqlite3_ran
37700 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  dom() */.#define
37710 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
37720 41 54 49 43 5f 4c 52 55 20 20 20 20 20 20 20 36  ATIC_LRU       6
37730 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69    /* lru page li
37740 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
37750 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
37760 43 5f 4c 52 55 32 20 20 20 20 20 20 37 20 20 2f  C_LRU2      7  /
37770 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20  * lru page list 
37780 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
37790 45 46 3a 20 52 65 74 72 69 65 76 65 20 74 68 65  EF: Retrieve the
377a0 20 6d 75 74 65 78 20 66 6f 72 20 61 20 64 61 74   mutex for a dat
377b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
377c0 20 7b 48 31 37 30 30 32 7d 20 3c 48 31 37 30 30   {H17002} <H1700
377d0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0>.**.** This in
377e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
377f0 61 20 70 6f 69 6e 74 65 72 20 74 68 65 20 5b 73  a pointer the [s
37800 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
37810 6a 65 63 74 20 74 68 61 74 20 0a 2a 2a 20 73 65  ject that .** se
37820 72 69 61 6c 69 7a 65 73 20 61 63 63 65 73 73 20  rializes access 
37830 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
37840 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 67 69 76   connection] giv
37850 65 6e 20 69 6e 20 74 68 65 20 61 72 67 75 6d 65  en in the argume
37860 6e 74 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 5b  nt.** when the [
37870 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
37880 69 73 20 53 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  is Serialized..*
37890 2a 20 49 66 20 74 68 65 20 5b 74 68 72 65 61 64  * If the [thread
378a0 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 69 6e  ing mode] is Sin
378b0 67 6c 65 2d 74 68 72 65 61 64 20 6f 72 20 4d 75  gle-thread or Mu
378c0 6c 74 69 2d 74 68 72 65 61 64 20 74 68 65 6e 20  lti-thread then 
378d0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
378e0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
378f0 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74  ointer..*/.sqlit
37900 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65  e3_mutex *sqlite
37910 33 5f 64 62 5f 6d 75 74 65 78 28 73 71 6c 69 74  3_db_mutex(sqlit
37920 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
37930 49 33 52 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c  I3REF: Low-Level
37940 20 43 6f 6e 74 72 6f 6c 20 4f 66 20 44 61 74 61   Control Of Data
37950 62 61 73 65 20 46 69 6c 65 73 20 7b 48 31 31 33  base Files {H113
37960 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a  00} <S30800>.**.
37970 2a 2a 20 7b 48 31 31 33 30 31 7d 20 54 68 65 20  ** {H11301} The 
37980 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
37990 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
379a0 63 65 20 6d 61 6b 65 73 20 61 20 64 69 72 65 63  ce makes a direc
379b0 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a  t call to the.**
379c0 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
379d0 74 68 6f 64 20 66 6f 72 20 74 68 65 20 5b 73 71  thod for the [sq
379e0 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
379f0 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
37a00 74 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 70 61  ted.** with a pa
37a10 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
37a20 65 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  e identified by 
37a30 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
37a40 65 6e 74 2e 20 7b 48 31 31 33 30 32 7d 20 54 68  ent. {H11302} Th
37a50 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65  e.** name of the
37a60 20 64 61 74 61 62 61 73 65 20 69 73 20 74 68 65   database is the
37a70 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
37a80 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62  o the database b
37a90 79 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  y the.** <a href
37aa0 3d 22 6c 61 6e 67 5f 61 74 74 61 63 68 2e 68 74  ="lang_attach.ht
37ab0 6d 6c 22 3e 41 54 54 41 43 48 3c 2f 61 3e 20 53  ml">ATTACH</a> S
37ac0 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 68 61 74 20  QL command that 
37ad0 6f 70 65 6e 65 64 20 74 68 65 0a 2a 2a 20 64 61  opened the.** da
37ae0 74 61 62 61 73 65 2e 20 7b 48 31 31 33 30 33 7d  tabase. {H11303}
37af0 20 54 6f 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20   To control the 
37b00 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
37b10 6c 65 2c 20 75 73 65 20 74 68 65 20 6e 61 6d 65  le, use the name
37b20 20 22 6d 61 69 6e 22 0a 2a 2a 20 6f 72 20 61 20   "main".** or a 
37b30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 7b 48  NULL pointer. {H
37b40 31 31 33 30 34 7d 20 54 68 65 20 74 68 69 72 64  11304} The third
37b50 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
37b60 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 72  meters to this r
37b70 6f 75 74 69 6e 65 0a 2a 2a 20 61 72 65 20 70 61  outine.** are pa
37b80 73 73 65 64 20 64 69 72 65 63 74 6c 79 20 74 68  ssed directly th
37b90 72 6f 75 67 68 20 74 6f 20 74 68 65 20 73 65 63  rough to the sec
37ba0 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 70 61  ond and third pa
37bb0 72 61 6d 65 74 65 72 73 20 6f 66 0a 2a 2a 20 74  rameters of.** t
37bc0 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
37bd0 6d 65 74 68 6f 64 2e 20 20 7b 48 31 31 33 30 35  method.  {H11305
37be0 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
37bf0 75 65 20 6f 66 20 74 68 65 20 78 46 69 6c 65 43  ue of the xFileC
37c00 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68 6f 64  ontrol.** method
37c10 20 62 65 63 6f 6d 65 73 20 74 68 65 20 72 65 74   becomes the ret
37c20 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
37c30 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a  s routine..**.**
37c40 20 7b 48 31 31 33 30 36 7d 20 49 66 20 74 68 65   {H11306} If the
37c50 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
37c60 72 20 28 7a 44 62 4e 61 6d 65 29 20 64 6f 65 73  r (zDbName) does
37c70 20 6e 6f 74 20 6d 61 74 63 68 20 74 68 65 20 6e   not match the n
37c80 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 70  ame of any.** op
37c90 65 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  en database file
37ca0 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 45 52  , then SQLITE_ER
37cb0 52 4f 52 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ROR is returned.
37cc0 20 7b 48 31 31 33 30 37 7d 20 54 68 69 73 20 65   {H11307} This e
37cd0 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
37ce0 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65 64 20 61  not remembered a
37cf0 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 72  nd will not be r
37d00 65 63 61 6c 6c 65 64 20 62 79 20 5b 73 71 6c 69  ecalled by [sqli
37d10 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 0a 2a  te3_errcode()].*
37d20 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  * or [sqlite3_er
37d30 72 6d 73 67 28 29 5d 2e 20 7b 41 31 31 33 30 38  rmsg()]. {A11308
37d40 7d 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  } The underlying
37d50 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
37d60 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a 20 61 6c  thod might.** al
37d70 73 6f 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  so return SQLITE
37d80 5f 45 52 52 4f 52 2e 20 20 7b 41 31 31 33 30 39  _ERROR.  {A11309
37d90 7d 20 54 68 65 72 65 20 69 73 20 6e 6f 20 77 61  } There is no wa
37da0 79 20 74 6f 20 64 69 73 74 69 6e 67 75 69 73 68  y to distinguish
37db0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61 6e 20 69   between.** an i
37dc0 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e 61 6d 65  ncorrect zDbName
37dd0 20 61 6e 64 20 61 6e 20 53 51 4c 49 54 45 5f 45   and an SQLITE_E
37de0 52 52 4f 52 20 72 65 74 75 72 6e 20 66 72 6f 6d  RROR return from
37df0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a   the underlying.
37e00 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  ** xFileControl 
37e10 6d 65 74 68 6f 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  method. {END}.**
37e20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53  .** See also: [S
37e30 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
37e40 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71  STATE].*/.int sq
37e50 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
37e60 6f 6c 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  ol(sqlite3*, con
37e70 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
37e80 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 2a 29  , int op, void*)
37e90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37ea0 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65 72  F: Testing Inter
37eb0 66 61 63 65 20 7b 48 31 31 34 30 30 7d 20 3c 53  face {H11400} <S
37ec0 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30800>.**.** The
37ed0 20 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f   sqlite3_test_co
37ee0 6e 74 72 6f 6c 28 29 20 69 6e 74 65 72 66 61 63  ntrol() interfac
37ef0 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61  e is used to rea
37f00 64 20 6f 75 74 20 69 6e 74 65 72 6e 61 6c 0a 2a  d out internal.*
37f10 2a 20 73 74 61 74 65 20 6f 66 20 53 51 4c 69 74  * state of SQLit
37f20 65 20 61 6e 64 20 74 6f 20 69 6e 6a 65 63 74 20  e and to inject 
37f30 66 61 75 6c 74 73 20 69 6e 74 6f 20 53 51 4c 69  faults into SQLi
37f40 74 65 20 66 6f 72 20 74 65 73 74 69 6e 67 0a 2a  te for testing.*
37f50 2a 20 70 75 72 70 6f 73 65 73 2e 20 20 54 68 65  * purposes.  The
37f60 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
37f70 20 69 73 20 61 6e 20 6f 70 65 72 61 74 69 6f 6e   is an operation
37f80 20 63 6f 64 65 20 74 68 61 74 20 64 65 74 65 72   code that deter
37f90 6d 69 6e 65 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  mines.** the num
37fa0 62 65 72 2c 20 6d 65 61 6e 69 6e 67 2c 20 61 6e  ber, meaning, an
37fb0 64 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 61  d operation of a
37fc0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 70 61  ll subsequent pa
37fd0 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  rameters..**.** 
37fe0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  This interface i
37ff0 73 20 6e 6f 74 20 66 6f 72 20 75 73 65 20 62 79  s not for use by
38000 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 2e 20 20   applications.  
38010 49 74 20 65 78 69 73 74 73 20 73 6f 6c 65 6c 79  It exists solely
38020 0a 2a 2a 20 66 6f 72 20 76 65 72 69 66 79 69 6e  .** for verifyin
38030 67 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 70  g the correct op
38040 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  eration of the S
38050 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
38060 44 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20  Depending.** on 
38070 68 6f 77 20 74 68 65 20 53 51 4c 69 74 65 20 6c  how the SQLite l
38080 69 62 72 61 72 79 20 69 73 20 63 6f 6d 70 69 6c  ibrary is compil
38090 65 64 2c 20 74 68 69 73 20 69 6e 74 65 72 66 61  ed, this interfa
380a0 63 65 20 6d 69 67 68 74 20 6e 6f 74 20 65 78 69  ce might not exi
380b0 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  st..**.** The de
380c0 74 61 69 6c 73 20 6f 66 20 74 68 65 20 6f 70 65  tails of the ope
380d0 72 61 74 69 6f 6e 20 63 6f 64 65 73 2c 20 74 68  ration codes, th
380e0 65 69 72 20 6d 65 61 6e 69 6e 67 73 2c 20 74 68  eir meanings, th
380f0 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  e parameters.** 
38100 74 68 65 79 20 74 61 6b 65 2c 20 61 6e 64 20 77  they take, and w
38110 68 61 74 20 74 68 65 79 20 64 6f 20 61 72 65 20  hat they do are 
38120 61 6c 6c 20 73 75 62 6a 65 63 74 20 74 6f 20 63  all subject to c
38130 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f  hange without no
38140 74 69 63 65 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 20  tice..** Unlike 
38150 6d 6f 73 74 20 6f 66 20 74 68 65 20 53 51 4c 69  most of the SQLi
38160 74 65 20 41 50 49 2c 20 74 68 69 73 20 66 75 6e  te API, this fun
38170 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 75 61  ction is not gua
38180 72 61 6e 74 65 65 64 20 74 6f 0a 2a 2a 20 6f 70  ranteed to.** op
38190 65 72 61 74 65 20 63 6f 6e 73 69 73 74 65 6e 74  erate consistent
381a0 6c 79 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65  ly from one rele
381b0 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ase to the next.
381c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
381d0 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 69 6e 74  test_control(int
381e0 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
381f0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
38200 69 6e 67 20 49 6e 74 65 72 66 61 63 65 20 4f 70  ing Interface Op
38210 65 72 61 74 69 6f 6e 20 43 6f 64 65 73 20 7b 48  eration Codes {H
38220 31 31 34 31 30 7d 20 3c 48 31 31 34 30 30 3e 0a  11410} <H11400>.
38230 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
38240 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 76 61  tants are the va
38250 6c 69 64 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f  lid operation co
38260 64 65 20 70 61 72 61 6d 65 74 65 72 73 20 75 73  de parameters us
38270 65 64 0a 2a 2a 20 61 73 20 74 68 65 20 66 69 72  ed.** as the fir
38280 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  st argument to [
38290 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e  sqlite3_test_con
382a0 74 72 6f 6c 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  trol()]..**.** T
382b0 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20  hese parameters 
382c0 61 6e 64 20 74 68 65 69 72 20 6d 65 61 6e 69 6e  and their meanin
382d0 67 73 20 61 72 65 20 73 75 62 6a 65 63 74 20 74  gs are subject t
382e0 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 77 69 74 68  o change.** with
382f0 6f 75 74 20 6e 6f 74 69 63 65 2e 20 20 54 68 65  out notice.  The
38300 73 65 20 76 61 6c 75 65 73 20 61 72 65 20 66 6f  se values are fo
38310 72 20 74 65 73 74 69 6e 67 20 70 75 72 70 6f 73  r testing purpos
38320 65 73 20 6f 6e 6c 79 2e 0a 2a 2a 20 41 70 70 6c  es only..** Appl
38330 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
38340 6e 6f 74 20 75 73 65 20 61 6e 79 20 6f 66 20 74  not use any of t
38350 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20  hese parameters 
38360 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  or the.** [sqlit
38370 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28  e3_test_control(
38380 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
38390 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
383a0 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 53 41  TESTCTRL_PRNG_SA
383b0 56 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  VE              
383c0 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
383d0 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47  TE_TESTCTRL_PRNG
383e0 5f 52 45 53 54 4f 52 45 20 20 20 20 20 20 20 20  _RESTORE        
383f0 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
38400 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50  QLITE_TESTCTRL_P
38410 52 4e 47 5f 52 45 53 45 54 20 20 20 20 20 20 20  RNG_RESET       
38420 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
38430 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52  e SQLITE_TESTCTR
38440 4c 5f 42 49 54 56 45 43 5f 54 45 53 54 20 20 20  L_BITVEC_TEST   
38450 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
38460 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54  fine SQLITE_TEST
38470 43 54 52 4c 5f 46 41 55 4c 54 5f 49 4e 53 54 41  CTRL_FAULT_INSTA
38480 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 39 0a  LL            9.
38490 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
384a0 45 53 54 43 54 52 4c 5f 42 45 4e 49 47 4e 5f 4d  ESTCTRL_BENIGN_M
384b0 41 4c 4c 4f 43 5f 48 4f 4f 4b 53 20 20 20 20 20  ALLOC_HOOKS     
384c0 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
384d0 45 5f 54 45 53 54 43 54 52 4c 5f 50 45 4e 44 49  E_TESTCTRL_PENDI
384e0 4e 47 5f 42 59 54 45 20 20 20 20 20 20 20 20 20  NG_BYTE         
384f0 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
38500 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 41 53  LITE_TESTCTRL_AS
38510 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
38520 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
38530 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
38540 5f 41 4c 57 41 59 53 20 20 20 20 20 20 20 20 20  _ALWAYS         
38550 20 20 20 20 20 20 20 20 20 31 33 0a 23 64 65 66           13.#def
38560 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
38570 54 52 4c 5f 52 45 53 45 52 56 45 20 20 20 20 20  TRL_RESERVE     
38580 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 0a              14..
38590 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
385a0 53 51 4c 69 74 65 20 52 75 6e 74 69 6d 65 20 53  SQLite Runtime S
385b0 74 61 74 75 73 20 7b 48 31 37 32 30 30 7d 20 3c  tatus {H17200} <
385c0 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S60200>.** EXPER
385d0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
385e0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
385f0 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
38600 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73 20   runtime status 
38610 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
38620 62 6f 75 74 20 74 68 65 20 70 72 65 66 6f 72 6d  bout the preform
38630 61 6e 63 65 20 6f 66 20 53 51 4c 69 74 65 2c 20  ance of SQLite, 
38640 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 74  and optionally t
38650 6f 20 72 65 73 65 74 20 76 61 72 69 6f 75 73 0a  o reset various.
38660 2a 2a 20 68 69 67 68 77 61 74 65 72 20 6d 61 72  ** highwater mar
38670 6b 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  ks.  The first a
38680 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
38690 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 0a 2a  teger code for.*
386a0 2a 20 74 68 65 20 73 70 65 63 69 66 69 63 20 70  * the specific p
386b0 61 72 61 6d 65 74 65 72 20 74 6f 20 6d 65 61 73  arameter to meas
386c0 75 72 65 2e 20 20 52 65 63 6f 67 6e 69 7a 65 64  ure.  Recognized
386d0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 0a 2a   integer codes.*
386e0 2a 20 61 72 65 20 6f 66 20 74 68 65 20 66 6f 72  * are of the for
386f0 6d 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 55 53  m [SQLITE_STATUS
38700 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 7c 20 53  _MEMORY_USED | S
38710 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 2e 2e 2e  QLITE_STATUS_...
38720 5d 2e 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e  ]..** The curren
38730 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 70  t value of the p
38740 61 72 61 6d 65 74 65 72 20 69 73 20 72 65 74 75  arameter is retu
38750 72 6e 65 64 20 69 6e 74 6f 20 2a 70 43 75 72 72  rned into *pCurr
38760 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 68 69 67 68  ent..** The high
38770 65 73 74 20 72 65 63 6f 72 64 65 64 20 76 61 6c  est recorded val
38780 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ue is returned i
38790 6e 20 2a 70 48 69 67 68 77 61 74 65 72 2e 20 20  n *pHighwater.  
387a0 49 66 20 74 68 65 0a 2a 2a 20 72 65 73 65 74 46  If the.** resetF
387b0 6c 61 67 20 69 73 20 74 72 75 65 2c 20 74 68 65  lag is true, the
387c0 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 72 65  n the highest re
387d0 63 6f 72 64 20 76 61 6c 75 65 20 69 73 20 72 65  cord value is re
387e0 73 65 74 20 61 66 74 65 72 0a 2a 2a 20 2a 70 48  set after.** *pH
387f0 69 67 68 77 61 74 65 72 20 69 73 20 77 72 69 74  ighwater is writ
38800 74 65 6e 2e 20 53 6f 6d 65 20 70 61 72 61 6d 65  ten. Some parame
38810 74 65 72 73 20 64 6f 20 6e 6f 74 20 72 65 63 6f  ters do not reco
38