/ Hex Artifact Content
Login

Artifact 65d5da2c6ce45bcaa11122f9e9398c015fba69ba:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 20 7b 48 31 30 30 31 30 7d 20 3c 53 36 30  rs {H10010} <S60
0ac0: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  100>.**.** The S
0ad0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 61 6e  QLITE_VERSION an
0ae0: 64 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  d SQLITE_VERSION
0af0: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 73  _NUMBER #defines
0b00: 20 69 6e 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74   in.** the sqlit
0b10: 65 33 2e 68 20 66 69 6c 65 20 73 70 65 63 69 66  e3.h file specif
0b20: 79 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f 66  y the version of
0b30: 20 53 51 4c 69 74 65 20 77 69 74 68 20 77 68 69   SQLite with whi
0b40: 63 68 0a 2a 2a 20 74 68 61 74 20 68 65 61 64 65  ch.** that heade
0b50: 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63 69  r file is associ
0b60: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
0b70: 22 76 65 72 73 69 6f 6e 22 20 6f 66 20 53 51 4c  "version" of SQL
0b80: 69 74 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  ite is a string 
0b90: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 57 2e 58  of the form "W.X
0ba0: 2e 59 22 20 6f 72 20 22 57 2e 58 2e 59 2e 5a 22  .Y" or "W.X.Y.Z"
0bb0: 2e 0a 2a 2a 20 54 68 65 20 57 20 76 61 6c 75 65  ..** The W value
0bc0: 20 69 73 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f   is major versio
0bd0: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 69 73 20  n number and is 
0be0: 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69  always 3 in SQLi
0bf0: 74 65 33 2e 0a 2a 2a 20 54 68 65 20 57 20 76 61  te3..** The W va
0c00: 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73  lue only changes
0c10: 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64 73 20   when backwards 
0c20: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73  compatibility is
0c30: 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77  .** broken and w
0c40: 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65  e intend to neve
0c50: 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61 72 64  r break backward
0c60: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
0c70: 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20  .** The X value 
0c80: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72  is the minor ver
0c90: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20  sion number and 
0ca0: 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65  only changes whe
0cb0: 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d  n.** there are m
0cc0: 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68  ajor feature enh
0cd0: 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61  ancements that a
0ce0: 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70  re forwards comp
0cf0: 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f  atible.** but no
0d00: 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  t backwards comp
0d10: 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 59  atible..** The Y
0d20: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 72 65   value is the re
0d30: 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61 6e 64  lease number and
0d40: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20   is incremented 
0d50: 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c  with.** each rel
0d60: 65 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20  ease but resets 
0d70: 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 65 76  back to 0 whenev
0d80: 65 72 20 58 20 69 73 20 69 6e 63 72 65 6d 65 6e  er X is incremen
0d90: 74 65 64 2e 0a 2a 2a 20 54 68 65 20 5a 20 76 61  ted..** The Z va
0da0: 6c 75 65 20 6f 6e 6c 79 20 61 70 70 65 61 72 73  lue only appears
0db0: 20 6f 6e 20 62 72 61 6e 63 68 20 72 65 6c 65 61   on branch relea
0dc0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ses..**.** The S
0dd0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0de0: 4d 42 45 52 20 69 73 20 61 6e 20 69 6e 74 65 67  MBER is an integ
0df0: 65 72 20 74 68 61 74 20 69 73 20 63 6f 6d 70 75  er that is compu
0e00: 74 65 64 20 61 73 0a 2a 2a 20 66 6f 6c 6c 6f 77  ted as.** follow
0e10: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
0e20: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 53 51  uote><pre>.** SQ
0e30: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
0e40: 42 45 52 20 3d 20 57 2a 31 30 30 30 30 30 30 20  BER = W*1000000 
0e50: 2b 20 58 2a 31 30 30 30 20 2b 20 59 0a 2a 2a 20  + X*1000 + Y.** 
0e60: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
0e70: 74 65 3e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20  te>.**.** Since 
0e80: 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20  version 3.6.18, 
0e90: 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f  SQLite source co
0ea0: 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72  de has been stor
0eb0: 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20  ed in the.** <a 
0ec0: 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77  href="http://www
0ed0: 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f  .fossil-scm.org/
0ee0: 22 3e 66 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75  ">fossil configu
0ef0: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e  ration managemen
0f00: 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e  t.** system</a>.
0f10: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55    The SQLITE_SOU
0f20: 52 43 45 5f 49 44 0a 2a 2a 20 6d 61 63 72 6f 20  RCE_ID.** macro 
0f30: 69 73 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  is a string whic
0f40: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0f50: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0f60: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0f70: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0f80: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0f90: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ent system.  The
0fa0: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73   string contains
0fb0: 20 74 68 65 0a 2a 2a 20 64 61 74 65 20 61 6e 64   the.** date and
0fc0: 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65   time of the che
0fd0: 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20  ck-in (UTC) and 
0fe0: 61 6e 20 53 48 41 31 20 68 61 73 68 20 6f 66 20  an SHA1 hash of 
0ff0: 74 68 65 20 65 6e 74 69 72 65 0a 2a 2a 20 73 6f  the entire.** so
1000: 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a  urce tree..**.**
1010: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1020: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1030: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ],.** [sqlite3_l
1040: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1050: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f  ()], [sqlite3_so
1060: 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73  urceid()],.** [s
1070: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d  qlite_version()]
1080: 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75   and [sqlite_sou
1090: 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rce_id()]..**.**
10a0: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
10b0: 48 31 30 30 31 31 5d 20 5b 48 31 30 30 31 34 5d  H10011] [H10014]
10c0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
10d0: 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20  TE_VERSION      
10e0: 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65    "--VERS--".#de
10f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
1100: 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52  ION_NUMBER --VER
1110: 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64  SION-NUMBER--.#d
1120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55  efine SQLITE_SOU
1130: 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53  RCE_ID      "--S
1140: 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a  OURCE-ID--"../*.
1150: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1160: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
1170: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48  rsion Numbers {H
1180: 31 30 30 32 30 7d 20 3c 53 36 30 31 30 30 3e 0a  10020} <S60100>.
1190: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
11a0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a  ite3_version.**.
11b0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61  ** These interfa
11c0: 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20  ces provide the 
11d0: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
11e0: 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   as the [SQLITE_
11f0: 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51  VERSION],.** [SQ
1200: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1210: 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  BER], and [SQLIT
1220: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 23 64 65  E_SOURCE_ID] #de
1230: 66 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61  fines in the hea
1240: 64 65 72 2c 0a 2a 2a 20 62 75 74 20 61 72 65 20  der,.** but are 
1250: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1260: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
1270: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
1280: 72 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75  r file.  Cautiou
1290: 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73  s.** programmers
12a0: 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61   might include a
12b0: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
12c0: 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ts in their appl
12d0: 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65  ication to.** ve
12e0: 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73  rify that values
12f0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1300: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  se interfaces ma
1310: 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69  tch the macros i
1320: 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c  n.** the header,
1330: 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65   and thus insure
1340: 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63   that the applic
1350: 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70  ation is.** comp
1360: 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69  iled with matchi
1370: 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68  ng library and h
1380: 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a  eader files..**.
1390: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
13a0: 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20  pre>.** assert( 
13b0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
13c0: 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c  on_number()==SQL
13d0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
13e0: 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  ER );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1400: 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54  sourceid(),SQLIT
1410: 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20  E_SOURCE_ID)==0 
1420: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
1430: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62  rcmp(sqlite3_lib
1440: 76 65 72 73 69 6f 6e 2c 53 51 4c 49 54 45 5f 56  version,SQLITE_V
1450: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
1460: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1470: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ote>.**.** The s
1480: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1490: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
14a0: 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20 69 6e  urns the same in
14b0: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a  formation as is.
14c0: 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ** in the sqlite
14d0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
14e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68  ng constant.  Th
14f0: 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  e function is pr
1500: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73  ovided.** for us
1510: 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20  e in DLLs since 
1520: 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c  DLL users usuall
1530: 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 64 69  y do not have di
1540: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
1550: 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e  tring.** constan
1560: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c  ts within the DL
1570: 4c 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 74  L.  Similarly, t
1580: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1590: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  eid() function.*
15a0: 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 61  * returns the sa
15b0: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
15c0: 73 20 69 73 20 69 6e 20 74 68 65 20 5b 53 51 4c  s is in the [SQL
15d0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 23  ITE_SOURCE_ID] #
15e0: 64 65 66 69 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  define of.** the
15f0: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2a   header file..**
1600: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1610: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d  qlite_version()]
1620: 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75   and [sqlite_sou
1630: 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rce_id()]..**.**
1640: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
1650: 48 31 30 30 32 31 5d 20 5b 48 31 30 30 32 32 5d  H10021] [H10022]
1660: 20 5b 48 31 30 30 32 33 5d 0a 2a 2f 0a 53 51 4c   [H10023].*/.SQL
1670: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
1680: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
1690: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
16a0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
16b0: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63  version(void);.c
16c0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
16d0: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
16e0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
16f0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1700: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1710: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f  API3REF: Test To
1720: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72   See If The Libr
1730: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66  ary Is Threadsaf
1740: 65 20 7b 48 31 30 31 30 30 7d 20 3c 53 36 30 31  e {H10100} <S601
1750: 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  00>.**.** SQLite
1760: 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64   can be compiled
1770: 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74   with or without
1780: 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a   mutexes.  When.
1790: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
17a0: 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 65  HREADSAFE] C pre
17b0: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
17c0: 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78  is 1 or 2, mutex
17d0: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
17e0: 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20  d and SQLite is 
17f0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 65  threadsafe.  Whe
1800: 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  n the.** [SQLITE
1810: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63  _THREADSAFE] mac
1820: 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65  ro is 0, .** the
1830: 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69   mutexes are omi
1840: 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74  tted.  Without t
1850: 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69  he mutexes, it i
1860: 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f  s not safe.** to
1870: 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63   use SQLite conc
1880: 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f  urrently from mo
1890: 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65  re than one thre
18a0: 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69  ad..**.** Enabli
18b0: 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72  ng mutexes incur
18c0: 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70  s a measurable p
18d0: 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c  erformance penal
18e0: 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65  ty..** So if spe
18f0: 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20  ed is of utmost 
1900: 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d  importance, it m
1910: 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69  akes sense to di
1920: 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74  sable.** the mut
1930: 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d  exes.  But for m
1940: 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d  aximum safety, m
1950: 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65  utexes should be
1960: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65   enabled..** The
1970: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
1980: 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73  r is for mutexes
1990: 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a   to be enabled..
19a0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
19b0: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
19c0: 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69   by an applicati
19d0: 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  on to make sure 
19e0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73  that the.** vers
19f0: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68  ion of SQLite th
1a00: 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67  at it is linking
1a10: 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d   against was com
1a20: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
1a30: 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e  e desired settin
1a40: 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  g of the [SQLITE
1a50: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63  _THREADSAFE] mac
1a60: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ro..**.** This i
1a70: 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65  nterface only re
1a80: 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d  ports on the com
1a90: 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20  pile-time mutex 
1aa0: 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68  setting.** of th
1ab0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1ac0: 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20  SAFE] flag.  If 
1ad0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
1ae0: 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54  ed with.** SQLIT
1af0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 74  E_THREADSAFE=1 t
1b00: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
1b10: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
1b20: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
1b30: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
1b40: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
1b50: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
1b60: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
1b70: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
1b80: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
1b90: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
1ba0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
1bb0: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
1bc0: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
1bd0: 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20 72  G_MUTEX].  The r
1be0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1bf0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
1c00: 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20 64  ws.** only the d
1c10: 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d 74  efault compile-t
1c20: 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f 74  ime setting, not
1c30: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68   any run-time ch
1c40: 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61 74  anges.** to that
1c50: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
1c60: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  See the [threadi
1c70: 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e  ng mode] documen
1c80: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
1c90: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
1ca0: 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  n..**.** Require
1cb0: 6d 65 6e 74 73 3a 20 5b 48 31 30 31 30 31 5d 20  ments: [H10101] 
1cc0: 5b 48 31 30 31 30 32 5d 0a 2a 2f 0a 69 6e 74 20  [H10102].*/.int 
1cd0: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1ce0: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  fe(void);../*.**
1cf0: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
1d00: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48  ase Connection H
1d10: 61 6e 64 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c  andle {H12000} <
1d20: 53 34 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S40200>.** KEYWO
1d30: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63  RDS: {database c
1d40: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61  onnection} {data
1d50: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1d60: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65  }.**.** Each ope
1d70: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
1d80: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  e is represented
1d90: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   by a pointer to
1da0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a   an instance of.
1db0: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74  ** the opaque st
1dc0: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73  ructure named "s
1dd0: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20  qlite3".  It is 
1de0: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20  useful to think 
1df0: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a  of an sqlite3.**
1e00: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f   pointer as an o
1e10: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c  bject.  The [sql
1e20: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1e30: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1e40: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1e50: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
1e60: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20  erfaces are its 
1e70: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e  constructors, an
1e80: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
1e90: 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65  ()].** is its de
1ea0: 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65  structor.  There
1eb0: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20   are many other 
1ec0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
1ed0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
1ee0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
1ef0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
1f00: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
1f10: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
1f20: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
1f30: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
1f40: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
1f50: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
1f60: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
1f70: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
1f80: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
1f90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
1fa0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
1fb0: 73 20 7b 48 31 30 32 30 30 7d 20 3c 53 31 30 31  s {H10200} <S101
1fc0: 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  10>.** KEYWORDS:
1fd0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
1fe0: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
1ff0: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2000: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2010: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2020: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2030: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2040: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2050: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
2060: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
2070: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
2080: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2090: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
20a0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
20b0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
20c0: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
20d0: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
20e0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
20f0: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2100: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2110: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2120: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2130: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
2140: 5b 48 31 30 32 30 31 5d 20 5b 48 31 30 32 30 32  [H10201] [H10202
2150: 5d 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ].*/.#ifdef SQLI
2160: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  TE_INT64_TYPE.  
2170: 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49  typedef SQLITE_I
2180: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2190: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
21a0: 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54  f unsigned SQLIT
21b0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
21c0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69  ite_uint64;.#eli
21d0: 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56  f defined(_MSC_V
21e0: 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f  ER) || defined(_
21f0: 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74  _BORLANDC__).  t
2200: 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73  ypedef __int64 s
2210: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
2220: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2230: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  __int64 sqlite_u
2240: 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74  int64;.#else.  t
2250: 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67  ypedef long long
2260: 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36   int sqlite_int6
2270: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2280: 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20  igned long long 
2290: 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  int sqlite_uint6
22a0: 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65  4;.#endif.typede
22b0: 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  f sqlite_int64 s
22c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79  qlite3_int64;.ty
22d0: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e  pedef sqlite_uin
22e0: 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  t64 sqlite3_uint
22f0: 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f  64;../*.** If co
2300: 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72  mpiling for a pr
2310: 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63  ocessor that lac
2320: 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  ks floating poin
2330: 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75  t support,.** su
2340: 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72  bstitute integer
2350: 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f   for floating-po
2360: 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  int..*/.#ifdef S
2370: 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54  QLITE_OMIT_FLOAT
2380: 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69  ING_POINT.# defi
2390: 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  ne double sqlite
23a0: 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a  3_int64.#endif..
23b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23c0: 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61  Closing A Databa
23d0: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48  se Connection {H
23e0: 31 32 30 31 30 7d 20 3c 53 33 30 31 30 30 3e 3c  12010} <S30100><
23f0: 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40200>.**.** Th
2400: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68  is routine is th
2410: 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  e destructor for
2420: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2430: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  bject..**.** App
2440: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b  lications must [
2450: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2460: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2470: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2480: 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ments].** and [s
2490: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
24a0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
24b0: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73  BLOB handles] as
24c0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
24d0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
24e0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
24f0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2500: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a  se the object..*
2510: 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  *.** If [sqlite3
2520: 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76  _close()] is inv
2530: 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61  oked while a tra
2540: 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nsaction is open
2550: 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63  ,.** the transac
2560: 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69  tion is automati
2570: 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
2580: 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70  k..**.** The C p
2590: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
25a0: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d  ite3_close(C)] m
25b0: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
25c0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
25d0: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
25e0: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
25f0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
2600: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
2610: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
2620: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
2630: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
2640: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
2650: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  sly closed..**.*
2660: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
2670: 2a 2a 20 5b 48 31 32 30 31 31 5d 20 5b 48 31 32  ** [H12011] [H12
2680: 30 31 32 5d 20 5b 48 31 32 30 31 33 5d 20 5b 48  012] [H12013] [H
2690: 31 32 30 31 34 5d 20 5b 48 31 32 30 31 35 5d 20  12014] [H12015] 
26a0: 5b 48 31 32 30 31 39 5d 0a 2a 2f 0a 69 6e 74 20  [H12019].*/.int 
26b0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71  sqlite3_close(sq
26c0: 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  lite3 *);../*.**
26d0: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
26e0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
26f0: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
2700: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
2710: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
2720: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
2730: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
2740: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
2750: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
2760: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
2770: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
2780: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
2790: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
27a0: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
27b0: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
27c0: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 7b 48  ion Interface {H
27d0: 31 32 31 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a  12100} <S10000>.
27e0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27f0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
2800: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
2810: 6e 74 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e  nt way of runnin
2820: 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  g one or more.**
2830: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
2840: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
2850: 6f 20 77 72 69 74 65 20 61 20 6c 6f 74 20 6f 66  o write a lot of
2860: 20 43 20 63 6f 64 65 2e 20 20 54 68 65 20 55 54   C code.  The UT
2870: 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 53  F-8 encoded.** S
2880: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
2890: 65 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  e passed in as t
28a0: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
28b0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
28c0: 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 74  xec()..** The st
28d0: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61  atements are eva
28e0: 6c 75 61 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e  luated one by on
28f0: 65 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61  e until either a
2900: 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a 20 61 6e  n error or.** an
2910: 20 69 6e 74 65 72 72 75 70 74 20 69 73 20 65 6e   interrupt is en
2920: 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72 20 75 6e  countered, or un
2930: 74 69 6c 20 74 68 65 79 20 61 72 65 20 61 6c 6c  til they are all
2940: 20 64 6f 6e 65 2e 20 20 54 68 65 20 33 72 64 20   done.  The 3rd 
2950: 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20  parameter.** is 
2960: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63 61 6c 6c  an optional call
2970: 62 61 63 6b 20 74 68 61 74 20 69 73 20 69 6e 76  back that is inv
2980: 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  oked once for ea
2990: 63 68 20 72 6f 77 20 6f 66 20 61 6e 79 20 71 75  ch row of any qu
29a0: 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74 73 20 70  ery.** results p
29b0: 72 6f 64 75 63 65 64 20 62 79 20 74 68 65 20 53  roduced by the S
29c0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
29d0: 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
29e0: 72 20 74 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a  r tells where.**
29f0: 20 74 6f 20 77 72 69 74 65 20 61 6e 79 20 65 72   to write any er
2a00: 72 6f 72 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a  ror messages..**
2a10: 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72 20 6d 65  .** The error me
2a20: 73 73 61 67 65 20 70 61 73 73 65 64 20 62 61 63  ssage passed bac
2a30: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
2a40: 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 68  h parameter is h
2a50: 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79  eld.** in memory
2a60: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2a70: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2a80: 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20 61 20 6d  ].  To avoid a m
2a90: 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74  emory leak,.** t
2aa0: 68 65 20 63 61 6c 6c 69 6e 67 20 61 70 70 6c 69  he calling appli
2ab0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 63 61  cation should ca
2ac0: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
2ad0: 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72 72 6f 72  ()] on any error
2ae0: 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72 65 74 75  .** message retu
2af0: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
2b00: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 77   5th parameter w
2b10: 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
2b20: 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hed using.** the
2b30: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
2b40: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
2b50: 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
2b60: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2b70: 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d  is NULL or an em
2b80: 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a 20 6f 72  pty string.** or
2b90: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69   a string contai
2ba0: 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69 74 65 73  ning only whites
2bb0: 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  pace and comment
2bc0: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 0a 2a  s, then no SQL.*
2bd0: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  * statements are
2be0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
2bf0: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  he database is n
2c00: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a  ot changed..**.*
2c10: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
2c20: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ec() interface i
2c30: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e  s implemented in
2c40: 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71   terms of.** [sq
2c50: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c60: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2c70: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2c80: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
2c90: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2ca0: 65 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64  exec() routine d
2cb0: 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74  oes nothing to t
2cc0: 68 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74  he database that
2cd0: 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a   cannot be done.
2ce0: 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
2cf0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
2d00: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
2d10: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
2d20: 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  alize()]..**.** 
2d30: 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2d40: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
2d50: 65 78 65 63 28 29 5d 20 6d 75 73 74 20 62 65 20  exec()] must be 
2d60: 61 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65  an valid and ope
2d70: 6e 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  n.** [database c
2d80: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a  onnection]..**.*
2d90: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63  * The database c
2da0: 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
2db0: 6f 74 20 62 65 20 63 6c 6f 73 65 64 20 77 68 69  ot be closed whi
2dc0: 6c 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  le.** [sqlite3_e
2dd0: 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  xec()] is runnin
2de0: 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  g..**.** The cal
2df0: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
2e00: 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65  ould use [sqlite
2e10: 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65  3_free()] to fre
2e20: 65 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  e.** the memory 
2e30: 74 68 61 74 20 2a 65 72 72 6d 73 67 20 69 73 20  that *errmsg is 
2e40: 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 61 74  left pointing at
2e50: 20 6f 6e 63 65 20 74 68 65 20 65 72 72 6f 72 0a   once the error.
2e60: 2a 2a 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f  ** message is no
2e70: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
2e80: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 20 73 74  **.** The SQL st
2e90: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 20  atement text in 
2ea0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2eb0: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  r to [sqlite3_ex
2ec0: 65 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 72 65  ec()].** must re
2ed0: 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77  main unchanged w
2ee0: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78  hile [sqlite3_ex
2ef0: 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  ec()] is running
2f00: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
2f10: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 31 30 31  ents:.** [H12101
2f20: 5d 20 5b 48 31 32 31 30 32 5d 20 5b 48 31 32 31  ] [H12102] [H121
2f30: 30 34 5d 20 5b 48 31 32 31 30 35 5d 20 5b 48 31  04] [H12105] [H1
2f40: 32 31 30 37 5d 20 5b 48 31 32 31 31 30 5d 20 5b  2107] [H12110] [
2f50: 48 31 32 31 31 33 5d 20 5b 48 31 32 31 31 36 5d  H12113] [H12116]
2f60: 0a 2a 2a 20 5b 48 31 32 31 31 39 5d 20 5b 48 31  .** [H12119] [H1
2f70: 32 31 32 32 5d 20 5b 48 31 32 31 32 35 5d 20 5b  2122] [H12125] [
2f80: 48 31 32 31 33 31 5d 20 5b 48 31 32 31 33 34 5d  H12131] [H12134]
2f90: 20 5b 48 31 32 31 33 37 5d 20 5b 48 31 32 31 33   [H12137] [H1213
2fa0: 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  8].*/.int sqlite
2fb0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  3_exec(.  sqlite
2fc0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
2fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fe0: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
2ff0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
3000: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst char *sql,  
3010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3020: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20           /* SQL 
3030: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
3040: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
3050: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
3060: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
3070: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
3080: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
3090: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
30a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30b0: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
30c0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
30d0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
30e0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
30f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3100: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
3110: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
3120: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
3130: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b  : Result Codes {
3140: 48 31 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e  H10210} <S10700>
3150: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
3160: 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63  LITE_OK {error c
3170: 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65  ode} {error code
3180: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
3190: 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72  {result code} {r
31a0: 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a  esult codes}.**.
31b0: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
31c0: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
31d0: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
31e0: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
31f0: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
3200: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
3210: 64 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20  dicates success 
3220: 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  or failure..**.*
3230: 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65  * New error code
3240: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
3250: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
3260: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
3270: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51  ** See also: [SQ
3280: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
3290: 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  | extended resul
32a0: 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66  t codes].*/.#def
32b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
32c0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
32d0: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
32e0: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
32f0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
3300: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3310: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
3320: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
3330: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
3340: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
3350: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
3360: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
3370: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
3380: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
3390: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
33a0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
33b0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
33c0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
33d0: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
33e0: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
33f0: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
3400: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
3410: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
3420: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
3430: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
3440: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
3450: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
3460: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
3470: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
3480: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
3490: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
34a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
34b0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
34c0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
34d0: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
34e0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
34f0: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
3500: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
3510: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
3520: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3530: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
3540: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
3550: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
3560: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
3570: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3580: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
3590: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
35a0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
35b0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
35c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
35d0: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
35e0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
35f0: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
3600: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
3610: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
3620: 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20      12   /* NOT 
3630: 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72  USED. Table or r
3640: 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20  ecord not found 
3650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3660: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33  E_FULL        13
3670: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20     /* Insertion 
3680: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64  failed because d
3690: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20  atabase is full 
36a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
36b0: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34  E_CANTOPEN    14
36c0: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20     /* Unable to 
36d0: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
36e0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
36f0: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f  e SQLITE_PROTOCO
3700: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54  L    15   /* NOT
3710: 20 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20   USED. Database 
3720: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
3730: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
3740: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
3750: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61    16   /* Databa
3760: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23  se is empty */.#
3770: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
3780: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
3790: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
37a0: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
37b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37c0: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
37d0: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
37e0: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
37f0: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
3800: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
3810: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
3820: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
3830: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
3840: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3850: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
3860: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
3870: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
3880: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
3890: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
38a0: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
38b0: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
38c0: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
38d0: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
38e0: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
38f0: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
3900: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
3910: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
3920: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
3930: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
3940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3950: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
3960: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61   /* Auxiliary da
3970: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72  tabase format er
3980: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
3990: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20  QLITE_RANGE     
39a0: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61    25   /* 2nd pa
39b0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
39c0: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72  e3_bind out of r
39d0: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ange */.#define 
39e0: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20  SQLITE_NOTADB   
39f0: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20     26   /* File 
3a00: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e  opened that is n
3a10: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
3a20: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
3a30: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
3a40: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
3a50: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
3a60: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
3a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3a80: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
3a90: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
3aa0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
3ab0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
3ac0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
3ad0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
3ae0: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
3af0: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31  Result Codes {H1
3b00: 30 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  0220} <S10700>.*
3b10: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
3b20: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
3b30: 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  } {extended erro
3b40: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3b50: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
3b60: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78  result code} {ex
3b70: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
3b80: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74  des}.**.** In it
3b90: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  s default config
3ba0: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  uration, SQLite 
3bb0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74  API routines ret
3bc0: 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e  urn one of 26 in
3bd0: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  teger.** [SQLITE
3be0: 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  _OK | result cod
3bf0: 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65  es].  However, e
3c00: 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68  xperience has sh
3c10: 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66  own that many of
3c20: 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74  .** these result
3c30: 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63   codes are too c
3c40: 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20  oarse-grained.  
3c50: 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76  They do not prov
3c60: 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69  ide as.** much i
3c70: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
3c80: 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f   problems as pro
3c90: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c  grammers might l
3ca0: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f  ike.  In an effo
3cb0: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73  rt to.** address
3cc0: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72   this, newer ver
3cd0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
3ce0: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61  (version 3.3.8 a
3cf0: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
3d00: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
3d10: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
3d20: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
3d30: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
3d40: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
3d50: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
3d60: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65   The extended re
3d70: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65  sult codes are e
3d80: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
3d90: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64  ed.** on a per d
3da0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3db0: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74  on basis using t
3dc0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
3dd0: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
3de0: 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a  odes()] API..**.
3df0: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61  ** Some of the a
3e00: 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65  vailable extende
3e10: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
3e20: 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a  re listed here..
3e30: 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63  ** One may expec
3e40: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
3e50: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
3e60: 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78  codes will be ex
3e70: 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d  pand.** over tim
3e80: 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  e.  Software tha
3e90: 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20  t uses extended 
3ea0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f  result codes sho
3eb0: 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f  uld expect.** to
3ec0: 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20   see new result 
3ed0: 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20  codes in future 
3ee0: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
3ef0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  te..**.** The SQ
3f00: 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63  LITE_OK result c
3f10: 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62  ode will never b
3f20: 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20  e extended.  It 
3f30: 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62  will always.** b
3f40: 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a  e exactly zero..
3f50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3f60: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20  E_IOERR_READ    
3f70: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3f80: 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29  E_IOERR | (1<<8)
3f90: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3fa0: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
3fb0: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
3fc0: 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29  _IOERR | (2<<8))
3fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fe0: 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20  IOERR_WRITE     
3ff0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4000: 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a  IOERR | (3<<8)).
4010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4020: 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20  OERR_FSYNC      
4030: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4040: 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OERR | (4<<8)).#
4050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4060: 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20  ERR_DIR_FSYNC   
4070: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4080: 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64  ERR | (5<<8)).#d
4090: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
40a0: 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20  RR_TRUNCATE     
40b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
40c0: 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  RR | (6<<8)).#de
40d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
40e0: 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20  R_FSTAT         
40f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4100: 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66  R | (7<<8)).#def
4110: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4120: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _UNLOCK         
4130: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4140: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
4150: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4160: 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  RDLOCK          
4170: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4180: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
4190: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
41a0: 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
41b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
41c0: 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (10<<8)).#defin
41d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42  e SQLITE_IOERR_B
41e0: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20  LOCKED          
41f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4200: 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (11<<8)).#defin
4210: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e  e SQLITE_IOERR_N
4220: 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20  OMEM            
4230: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4240: 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (12<<8)).#defin
4250: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41  e SQLITE_IOERR_A
4260: 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20  CCESS           
4270: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4280: 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (13<<8)).#defin
4290: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
42a0: 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b  HECKRESERVEDLOCK
42b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
42c0: 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (14<<8)).#defin
42d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c  e SQLITE_IOERR_L
42e0: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  OCK             
42f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4300: 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (15<<8)).#defin
4310: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
4320: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20  LOSE            
4330: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4340: 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (16<<8)).#defin
4350: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
4360: 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  IR_CLOSE        
4370: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4380: 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (17<<8)).#defin
4390: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f  e SQLITE_LOCKED_
43a0: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
43b0: 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20   (SQLITE_LOCKED 
43c0: 7c 20 28 31 3c 3c 38 29 20 29 0a 0a 2f 2a 0a 2a  | (1<<8) )../*.*
43d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
43e0: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
43f0: 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48 31 30 32  Operations {H102
4400: 33 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48 31  30} <H11120> <H1
4410: 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  2700>.**.** Thes
4420: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
4430: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
4440: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
4450: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
4460: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
4470: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
4480: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
4490: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
44a0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f  e xOpen method o
44b0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
44c0: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
44d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44e0: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
44f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
4500: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
4510: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
4520: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4530: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
4540: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
4550: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
4560: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
4570: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4580: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
4590: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
45a0: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
45b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
45c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45d0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
45e0: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
45f0: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
4600: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4610: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
4620: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
4630: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4650: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
4660: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
4670: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4680: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4690: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
46a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
46b0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
46c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46d0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
46e0: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
46f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
4720: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
4730: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4740: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4750: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
4760: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
4770: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4790: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
47a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
47b0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
47c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
47d0: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
47e0: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
47f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
4800: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4810: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
4820: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
4830: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
4840: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
4850: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4860: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
4870: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
4880: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
4890: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
48a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
48b0: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
48c0: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
48d0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
48e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
48f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4900: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
4910: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
4920: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
4930: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
4940: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4950: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63  F: Device Charac
4960: 74 65 72 69 73 74 69 63 73 20 7b 48 31 30 32 34  teristics {H1024
4970: 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a  0} <H11120>.**.*
4980: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 61 70  * The xDeviceCap
4990: 61 62 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64  abilities method
49a0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
49b0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
49c0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
49d0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
49e0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
49f0: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
4a00: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
4a10: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
4a20: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
4a30: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
4a40: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
4a50: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
4a60: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
4a70: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
4a80: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
4a90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4aa0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
4ab0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
4ac0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
4ad0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
4ae0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
4af0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
4b00: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
4b10: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
4b20: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
4b30: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
4b40: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
4b50: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
4b60: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
4b70: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
4b80: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
4b90: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
4ba0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
4bb0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
4bc0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
4bd0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
4be0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
4bf0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
4c00: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
4c10: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
4c20: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
4c30: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
4c40: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
4c50: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
4c60: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
4c70: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
4c80: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
4c90: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
4ca0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
4cb0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
4cc0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4cd0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
4ce0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
4cf0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
4d00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
4d10: 31 32 20 20 20 20 20 20 20 30 78 30 30 30 30 30  12       0x00000
4d20: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
4d30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
4d40: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
4d50: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
4d60: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
4d70: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
4d80: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
4d90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
4da0: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
4db0: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  010.#define SQLI
4dc0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
4dd0: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
4de0: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
4df0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
4e00: 36 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  6K       0x00000
4e10: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
4e20: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
4e30: 32 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  2K       0x00000
4e40: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
4e50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
4e60: 34 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  4K       0x00000
4e70: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
4e80: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
4e90: 50 45 4e 44 20 20 20 20 20 30 78 30 30 30 30 30  PEND     0x00000
4ea0: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
4eb0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
4ec0: 49 41 4c 20 20 20 20 20 20 30 78 30 30 30 30 30  IAL      0x00000
4ed0: 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  400../*.** CAPI3
4ee0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
4ef0: 67 20 4c 65 76 65 6c 73 20 7b 48 31 30 32 35 30  g Levels {H10250
4f00: 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48 31 31 33  } <H11120> <H113
4f10: 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  10>.**.** SQLite
4f20: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
4f30: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
4f40: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
4f50: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
4f60: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
4f70: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
4f80: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
4f90: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
4fa0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
4fb0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
4fc0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
4fd0: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
4fe0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4ff0: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
5000: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
5010: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
5020: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
5030: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
5040: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
5050: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5060: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
5070: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5080: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
5090: 20 54 79 70 65 20 46 6c 61 67 73 20 7b 48 31 30   Type Flags {H10
50a0: 32 36 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 2a  260} <H11120>.**
50b0: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
50c0: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
50d0: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
50e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
50f0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
5100: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
5110: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
5120: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
5130: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
5140: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
5150: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
5160: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
5170: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
5180: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
5190: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
51a0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
51b0: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
51c0: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
51d0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
51e0: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
51f0: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
5200: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
5210: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
5220: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
5230: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
5240: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
5250: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
5260: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
5270: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
5280: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
5290: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
52a0: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
52b0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
52c0: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
52d0: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
52e0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
52f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
5300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5310: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
5320: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
5330: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5340: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
5350: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
5360: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
5370: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
5380: 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32 30  le {H11110} <S20
5390: 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  110>.**.** An [s
53a0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
53b0: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
53c0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
53d0: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
53e0: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
53f0: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
5400: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
5410: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
5420: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
5430: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
5440: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
5450: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
5460: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
5470: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
5480: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
5490: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
54a0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
54b0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
54c0: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
54d0: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
54e0: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
54f0: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
5500: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
5510: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
5520: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
5530: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
5540: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
5550: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
5560: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
5570: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
5580: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
5590: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
55a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
55b0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
55c0: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
55d0: 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31  hods Object {H11
55e0: 31 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a  120} <S20110>.**
55f0: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
5600: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
5610: 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e  lite3_vfs] xOpen
5620: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65   method populate
5630: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s an.** [sqlite3
5640: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f  _file] object (o
5650: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79  r, more commonly
5660: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  , a subclass of 
5670: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
5680: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69  file] object) wi
5690: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  th a pointer to 
56a0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
56b0: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54  his object..** T
56c0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
56d0: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75  es the methods u
56e0: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  sed to perform v
56f0: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e  arious operation
5700: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65  s.** against the
5710: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65   open file repre
5720: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73  sented by the [s
5730: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
5740: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ect..**.** If th
5750: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 73  e xOpen method s
5760: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
5770: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
5780: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
5790: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
57a0: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
57b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
57c0: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
57d0: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
57e0: 6e 20 69 66 20 74 68 65 20 78 4f 70 65 6e 20 72  n if the xOpen r
57f0: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20  eported that it 
5800: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  failed.  The.** 
5810: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76  only way to prev
5820: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43  ent a call to xC
5830: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  lose following a
5840: 20 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a 2a 2a   failed xOpen.**
5850: 20 69 73 20 66 6f 72 20 74 68 65 20 78 4f 70 65   is for the xOpe
5860: 6e 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  n to set the sql
5870: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
5880: 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20 4e 55  ds element to NU
5890: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
58a0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
58b0: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
58c0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
58d0: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
58e0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
58f0: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
5900: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
5910: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
5920: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
5930: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
5940: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
5950: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
5960: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
5970: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
5980: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
5990: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
59a0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
59b0: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
59c0: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
59d0: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
59e0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
59f0: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
5a00: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
5a10: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
5a20: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5a30: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
5a40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
5a50: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
5a60: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
5a70: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
5a80: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
5a90: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
5aa0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5ab0: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
5ac0: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
5ad0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
5ae0: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
5af0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
5b00: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
5b10: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
5b20: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
5b30: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
5b40: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
5b50: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
5b60: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
5b70: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
5b80: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
5b90: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
5ba0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
5bb0: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
5bc0: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
5bd0: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
5be0: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
5bf0: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
5c00: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
5c10: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
5c20: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
5c30: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
5c40: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
5c50: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
5c60: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
5c70: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
5c80: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
5c90: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
5ca0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
5cb0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
5cc0: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
5cd0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
5ce0: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
5cf0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
5d00: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
5d10: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
5d20: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
5d30: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
5d40: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
5d50: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
5d60: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
5d70: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
5d80: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
5d90: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
5da0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
5db0: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
5dc0: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
5dd0: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
5de0: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
5df0: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
5e00: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
5e10: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
5e20: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
5e30: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
5e40: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
5e50: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
5e60: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
5e70: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
5e80: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
5e90: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
5ea0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
5eb0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
5ec0: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
5ed0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
5ee0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
5ef0: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
5f00: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
5f10: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
5f20: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
5f30: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
5f40: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
5f50: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
5f60: 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a   conflicts..**.*
5f70: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
5f80: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
5f90: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
5fa0: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
5fb0: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
5fc0: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
5fd0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
5fe0: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
5ff0: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
6000: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
6010: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
6020: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
6030: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
6040: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
6050: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
6060: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
6070: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
6080: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
6090: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
60a0: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
60b0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
60c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
60d0: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
60e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
60f0: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
6100: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6110: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
6120: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6130: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
6140: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6150: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
6160: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6170: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
6180: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6190: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
61a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
61b0: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
61c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
61d0: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
61e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
61f0: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
6200: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6210: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
6220: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
6230: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6240: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6250: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
6260: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
6270: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6280: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6290: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
62a0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
62b0: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
62c0: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
62d0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
62e0: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
62f0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
6300: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
6310: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
6320: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6330: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6340: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6350: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6360: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6370: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
6380: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
6390: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
63a0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
63b0: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
63c0: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
63d0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
63e0: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
63f0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6400: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6410: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
6420: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
6430: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
6440: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6450: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6460: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
6470: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
6480: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
6490: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
64a0: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
64b0: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
64c0: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
64d0: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
64e0: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
64f0: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
6500: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
6510: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
6520: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
6530: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
6540: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
6550: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
6560: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
6570: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
6580: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
6590: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
65a0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
65b0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
65c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
65d0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
65e0: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
65f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
6600: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
6610: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
6620: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
6630: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
6640: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
6650: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6660: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
6670: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
6680: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
6690: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
66a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
66b0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
66c0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
66d0: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
66e0: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
66f0: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
6700: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6710: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
6720: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
6730: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
6740: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
6750: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
6760: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
6770: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
6780: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
6790: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
67a0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
67b0: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
67c0: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
67d0: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
67e0: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
67f0: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
6800: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
6810: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
6820: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
6830: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
6840: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
6850: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
6860: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
6870: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
6880: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
6890: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
68a0: 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30   Opcodes {H11310
68b0: 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a  } <S30800>.**.**
68c0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
68d0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
68e0: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
68f0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
6900: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
6910: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6920: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
6930: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
6940: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
6950: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
6960: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
6970: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
6980: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
6990: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
69a0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
69b0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
69c0: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
69d0: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
69e0: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
69f0: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
6a00: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
6a10: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6a20: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
6a30: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
6a40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
6a50: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
6a60: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6a70: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
6a80: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
6a90: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
6aa0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
6ab0: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
6ac0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
6ad0: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
6ae0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
6af0: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
6b00: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
6b10: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6b20: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
6b30: 41 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65  ATE        1.#de
6b40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
6b50: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
6b60: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
6b70: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
6b80: 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65  YFILE      3.#de
6b90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
6ba0: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
6bb0: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6bc0: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
6bd0: 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30  le {H17110} <S20
6be0: 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  130>.**.** The m
6bf0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
6c00: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
6c10: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
6c20: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
6c30: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
6c40: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
6c50: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
6c60: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
6c70: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
6c80: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
6c90: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
6ca0: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
6cb0: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
6cc0: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
6cd0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
6ce0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
6cf0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
6d00: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
6d10: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
6d20: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
6d30: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
6d40: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
6d50: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6d60: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
6d70: 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31  t {H11140} <S201
6d80: 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  00>.**.** An ins
6d90: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
6da0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
6db0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
6dc0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
6dd0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
6de0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
6df0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
6e00: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
6e10: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
6e20: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
6e30: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
6e40: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
6e50: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
6e60: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
6e70: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
6e80: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
6e90: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
6ea0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
6eb0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
6ec0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
6ed0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
6ee0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
6ef0: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
6f00: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
6f10: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
6f20: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
6f30: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
6f40: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
6f50: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
6f60: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
6f70: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
6f80: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
6f90: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
6fa0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
6fb0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
6fc0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
6fd0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
6fe0: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
6ff0: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7000: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7010: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7020: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
7030: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
7040: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
7050: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
7060: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
7070: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
7080: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
7090: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
70a0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
70b0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
70c0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
70d0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
70e0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
70f0: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
7100: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
7110: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
7120: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
7130: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
7140: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
7150: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
7160: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
7170: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
7180: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
7190: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
71a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
71b0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
71c0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
71d0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
71e0: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
71f0: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
7200: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
7210: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
7220: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
7230: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
7240: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
7250: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
7260: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
7270: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
7280: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
7290: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
72a0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
72b0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
72c0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
72d0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
72e0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
72f0: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
7300: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
7310: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
7320: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
7330: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
7340: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
7350: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
7360: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
7370: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
7380: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
7390: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
73a0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
73b0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
73c0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
73d0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
73e0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
73f0: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
7400: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
7410: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
7420: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
7430: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
7440: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
7450: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
7460: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
7470: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
7480: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
7490: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
74a0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
74b0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
74c0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
74d0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
74e0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
74f0: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
7500: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
7510: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
7520: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
7530: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
7540: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
7550: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
7560: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
7570: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
7580: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
7590: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
75a0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
75b0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
75c0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
75d0: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
75e0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
75f0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
7600: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
7610: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
7620: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
7630: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
7640: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
7650: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
7660: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
7670: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
7680: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
7690: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
76a0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
76b0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
76c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
76d0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
76e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
76f0: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
7700: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
7710: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
7720: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
7730: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
7740: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
7750: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
7760: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
7770: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
7780: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
7790: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
77a0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
77b0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
77c0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
77d0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
77e0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
77f0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
7800: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7810: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
7820: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
7830: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
7840: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
7850: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
7860: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7870: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
7880: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
7890: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
78a0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
78b0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
78c0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
78d0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
78e0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
78f0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
7900: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
7910: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
7920: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
7930: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
7940: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
7950: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
7960: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
7970: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
7980: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
7990: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
79a0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
79b0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
79c0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
79d0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
79e0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
79f0: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
7a00: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
7a10: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
7a20: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
7a30: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
7a40: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
7a50: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
7a60: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
7a70: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
7a80: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
7a90: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
7aa0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
7ab0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
7ac0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
7ad0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
7ae0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
7af0: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
7b00: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
7b10: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
7b20: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
7b30: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
7b40: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
7b50: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
7b60: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
7b70: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
7b80: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
7b90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
7ba0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
7bb0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7bc0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7bd0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
7be0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
7bf0: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
7c00: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
7c10: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
7c20: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
7c30: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
7c40: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
7c50: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
7c60: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
7c70: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
7c80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
7c90: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
7ca0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
7cb0: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
7cc0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
7cd0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
7ce0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
7cf0: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
7d00: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
7d10: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
7d20: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
7d30: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
7d40: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
7d50: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
7d60: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
7d70: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
7d80: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
7d90: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
7da0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
7db0: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
7dc0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
7dd0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
7de0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
7df0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
7e00: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
7e10: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
7e20: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
7e30: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
7e40: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
7e50: 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74  ..**.** At least
7e60: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
7e70: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
7e80: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
7e90: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
7ea0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
7eb0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
7ec0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
7ed0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
7ee0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
7ef0: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
7f00: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
7f10: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
7f20: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
7f30: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
7f40: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
7f50: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
7f60: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
7f70: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7f80: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
7f90: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
7fa0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7fb0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
7fc0: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
7fd0: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
7fe0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
7ff0: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
8000: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
8010: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
8020: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
8030: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
8040: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
8050: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
8060: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
8070: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
8080: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  l..**.** The fla
8090: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
80a0: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
80b0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
80c0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
80d0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
80e0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
80f0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
8100: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
8110: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
8120: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
8130: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
8140: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8150: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
8160: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
8170: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
8180: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
8190: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
81a0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
81b0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
81c0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
81d0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
81e0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
81f0: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
8200: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
8210: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
8220: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
8230: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
8240: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
8250: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
8260: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
8270: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8280: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8290: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
82a0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
82b0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
82c0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
82d0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
82e0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
82f0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8300: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8310: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
8320: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
8330: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
8340: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
8350: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
8360: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
8370: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
8380: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
8390: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
83a0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
83b0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
83c0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
83d0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
83e0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
83f0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
8400: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
8410: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
8420: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
8430: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
8440: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
8450: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
8460: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
8470: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
8480: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
8490: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
84a0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
84b0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
84c0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
84d0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
84e0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
84f0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
8500: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
8510: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
8520: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
8530: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
8540: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
8550: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
8560: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
8570: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
8580: 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ..**.*/.typedef 
8590: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
85a0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
85b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
85c0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
85d0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
85e0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
85f0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  sion number */. 
8600: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
8610: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
8620: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
8630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
8640: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
8650: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
8660: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
8670: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
8680: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
8690: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
86a0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
86b0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
86c0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
86d0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
86e0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
86f0: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
8700: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
8710: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
8720: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
8730: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
8740: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
8750: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
8760: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
8770: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
8780: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
8790: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
87a0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
87b0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
87c0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
87d0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
87e0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
87f0: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
8800: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
8810: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
8820: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
8830: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
8840: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
8850: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
8860: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
8870: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
8880: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
8890: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
88a0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
88b0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
88c0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
88d0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
88e0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
88f0: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
8900: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
8910: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
8920: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
8930: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
8940: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
8950: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
8960: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
8970: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
8980: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
8990: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
89a0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
89b0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
89c0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
89d0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
89e0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
89f0: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
8a00: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
8a10: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
8a20: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
8a30: 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   /* New fields m
8a40: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
8a50: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
8a60: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
8a70: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
8a80: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
8a90: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
8aa0: 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  . */.};../*.** C
8ab0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
8ac0: 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
8ad0: 46 53 20 6d 65 74 68 6f 64 20 7b 48 31 31 31 39  FS method {H1119
8ae0: 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a  0} <H11140>.**.*
8af0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
8b00: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
8b10: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
8b20: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
8b30: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
8b40: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
8b50: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
8b60: 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65  . {END}  They de
8b70: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
8b80: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
8b90: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
8ba0: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
8bb0: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
8bc0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
8bd0: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
8be0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
8bf0: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
8c00: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
8c10: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
8c20: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
8c30: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
8c40: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
8c50: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
8c60: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
8c70: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a  e and writable..
8c80: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
8c90: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
8ca0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
8cb0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
8cc0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
8cd0: 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  dable..*/.#defin
8ce0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
8cf0: 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
8d00: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
8d10: 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64  S_READWRITE 1.#d
8d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
8d30: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a  ESS_READ      2.
8d40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
8d50: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
8d60: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b  SQLite Library {
8d70: 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30 3e  H10130} <S20000>
8d80: 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30100>.**.** T
8d90: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
8da0: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
8db0: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
8dc0: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
8dd0: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
8de0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
8df0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
8e00: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
8e10: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
8e20: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
8e30: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a  nitialize()..**.
8e40: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
8e50: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8e60: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
8e70: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
8e80: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
8e90: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
8ea0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
8eb0: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
8ec0: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
8ed0: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
8ee0: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
8ef0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
8f00: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
8f10: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
8f20: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
8f30: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
8f40: 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74    Only an effect
8f50: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
8f60: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
8f70: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
8f80: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
8f90: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
8fa0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
8fb0: 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  -ops..**.** A ca
8fc0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
8fd0: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
8fe0: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
8ff0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
9000: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
9010: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9020: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
9030: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9040: 7a 65 28 29 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 61  ze().  Only.** a
9050: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
9060: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
9070: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
9080: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
9090: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 63  ..** All other c
90a0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
90b0: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
90c0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a  armless no-ops..
90d0: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
90e0: 72 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 74 65  r things, sqlite
90f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
9100: 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  hall invoke.** s
9110: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
9120: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 73 71  .  Similarly, sq
9130: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9140: 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65  .** shall invoke
9150: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
9160: 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
9170: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9180: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
9190: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
91a0: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20   success..** If 
91b0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
91c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
91d0: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
91e0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
91f0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
9200: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
9210: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
9220: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
9230: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
9240: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
9250: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
9260: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
9270: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  TE_OK]..**.** Th
9280: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9290: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
92a0: 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
92b0: 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
92c0: 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
92d0: 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
92e0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
92f0: 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
9300: 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
9310: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9320: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
9330: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
9340: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
9350: 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
9360: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
9370: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
9380: 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
9390: 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
93a0: 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
93b0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
93c0: 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
93d0: 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
93e0: 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
93f0: 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51    However, if SQ
9400: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
9410: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
9420: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
9430: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
9440: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
9450: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
9460: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
9470: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
9480: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
9490: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
94a0: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
94b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
94c0: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
94d0: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
94e0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
94f0: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
9500: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
9510: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
9520: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
9530: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
9540: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9550: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
9560: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
9570: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
9580: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
9590: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
95a0: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
95b0: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
95c0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
95d0: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
95e0: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
95f0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
9600: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
9610: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
9620: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
9630: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
9640: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
9650: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
9660: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
9670: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
9680: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
9690: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
96a0: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
96b0: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
96c0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
96d0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
96e0: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
96f0: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
9700: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
9710: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
9720: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
9730: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
9740: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
9750: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
9760: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
9770: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
9780: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
9790: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
97a0: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
97b0: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
97c0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
97d0: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
97e0: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
97f0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
9800: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
9810: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
9820: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
9830: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
9840: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
9850: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
9860: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9870: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
9880: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
9890: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
98a0: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
98b0: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
98c0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
98d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
98e0: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
98f0: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
9900: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
9910: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9920: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
9930: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
9940: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
9950: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
9960: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
9970: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
9980: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9990: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
99a0: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
99b0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
99c0: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
99d0: 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
99e0: 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
99f0: 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
9a00: 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
9a10: 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
9a20: 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
9a30: 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
9a40: 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
9a50: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
9a60: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
9a70: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
9a80: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
9a90: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
9aa0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
9ab0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
9ac0: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
9ad0: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
9ae0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
9af0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
9b00: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
9b10: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
9b20: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
9b30: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
9b40: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
9b50: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
9b60: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
9b70: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9b80: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
9b90: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
9ba0: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
9bb0: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
9bc0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
9bd0: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
9be0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
9bf0: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
9c00: 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 34  ite Library {H14
9c10: 31 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33  100} <S20000><S3
9c20: 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0200>.** EXPERIM
9c30: 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ENTAL.**.** The 
9c40: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
9c50: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
9c60: 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
9c70: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
9c80: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
9c90: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
9ca0: 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
9cb0: 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
9cc0: 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
9cd0: 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
9ce0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
9cf0: 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
9d00: 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
9d10: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
9d20: 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
9d30: 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
9d40: 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
9d50: 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
9d60: 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
9d70: 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
9d80: 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
9d90: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
9da0: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
9db0: 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
9dc0: 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c  dsafe.  The appl
9dd0: 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
9de0: 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  insure that no o
9df0: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
9e00: 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
9e10: 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
9e20: 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
9e30: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
9e40: 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68   running.  Furth
9e50: 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f  ermore, sqlite3_
9e60: 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20  config().** may 
9e70: 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
9e80: 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
9e90: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
9ea0: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
9eb0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
9ec0: 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
9ed0: 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
9ee0: 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f  utdown()]..** No
9ef0: 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61  te, however, tha
9f00: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
9f10: 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
9f20: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
9f30: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
9f40: 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
9f50: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
9f60: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
9f70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
9f80: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
9f90: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
9fa0: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
9fb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
9fc0: 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e  NGLETHREAD | con
9fd0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
9fe0: 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
9ff0: 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
a000: 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
a010: 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
a020: 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
a030: 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
a040: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
a050: 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
a060: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20  _SINGLETHREAD | 
a070: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
a080: 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
a090: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
a0a0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e  **.** When a con
a0b0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
a0c0: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
a0d0: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
a0e0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
a0f0: 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  ** If the option
a100: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
a110: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
a120: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
a130: 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
a140: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
a150: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
a160: 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65   code]..**.** Re
a170: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
a180: 48 31 34 31 30 33 5d 20 5b 48 31 34 31 30 36 5d  H14103] [H14106]
a190: 20 5b 48 31 34 31 32 30 5d 20 5b 48 31 34 31 32   [H14120] [H1412
a1a0: 33 5d 20 5b 48 31 34 31 32 36 5d 20 5b 48 31 34  3] [H14126] [H14
a1b0: 31 32 39 5d 20 5b 48 31 34 31 33 32 5d 20 5b 48  129] [H14132] [H
a1c0: 31 34 31 33 35 5d 0a 2a 2a 20 5b 48 31 34 31 33  14135].** [H1413
a1d0: 38 5d 20 5b 48 31 34 31 34 31 5d 20 5b 48 31 34  8] [H14141] [H14
a1e0: 31 34 34 5d 20 5b 48 31 34 31 34 37 5d 20 5b 48  144] [H14147] [H
a1f0: 31 34 31 35 30 5d 20 5b 48 31 34 31 35 33 5d 20  14150] [H14153] 
a200: 5b 48 31 34 31 35 36 5d 20 5b 48 31 34 31 35 39  [H14156] [H14159
a210: 5d 0a 2a 2a 20 5b 48 31 34 31 36 32 5d 20 5b 48  ].** [H14162] [H
a220: 31 34 31 36 35 5d 20 5b 48 31 34 31 36 38 5d 0a  14165] [H14168].
a230: 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
a240: 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
a250: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
a260: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
a270: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
a280: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a290: 69 6f 6e 73 20 20 7b 48 31 34 32 30 30 7d 20 3c  ions  {H14200} <
a2a0: 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S20000>.** EXPER
a2b0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
a2c0: 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
a2d0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
a2e0: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
a2f0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
a300: 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
a310: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
a320: 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
a330: 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
a340: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
a350: 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
a360: 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
a370: 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
a380: 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
a390: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
a3a0: 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
a3b0: 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 54  st argument).  T
a3c0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62  he.** sqlite3_db
a3d0: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
a3e0: 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ace can only be 
a3f0: 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  used immediately
a400: 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61   after.** the da
a410: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
a420: 6e 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69  n is created usi
a430: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ng [sqlite3_open
a440: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
a450: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b  _open16()], or [
a460: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
a470: 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  )].  .**.** The 
a480: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
a490: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
a4a0: 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69  nfig(D,V,...)  i
a4b0: 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  s the.** configu
a4c0: 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e  ration verb - an
a4d0: 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
a4e0: 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
a4f0: 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74  t.** aspect of t
a500: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
a510: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
a520: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
a530: 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65   The only choice
a540: 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20   for this value 
a550: 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  is [SQLITE_DBCON
a560: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a  FIG_LOOKASIDE]..
a570: 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72 65  ** New verbs are
a580: 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64   likely to be ad
a590: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
a5a0: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
a5b0: 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
a5c0: 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64  arguments depend
a5d0: 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a   on the verb..**
a5e0: 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
a5f0: 3a 0a 2a 2a 20 5b 48 31 34 32 30 33 5d 20 5b 48  :.** [H14203] [H
a600: 31 34 32 30 36 5d 20 5b 48 31 34 32 30 39 5d 20  14206] [H14209] 
a610: 5b 48 31 34 32 31 32 5d 20 5b 48 31 34 32 31 35  [H14212] [H14215
a620: 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45  ].*/.SQLITE_EXPE
a630: 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c  RIMENTAL int sql
a640: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
a650: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
a660: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
a670: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
a680: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
a690: 65 73 20 7b 48 31 30 31 35 35 7d 20 3c 53 32 30  es {H10155} <S20
a6a0: 31 32 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  120>.** EXPERIME
a6b0: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  NTAL.**.** An in
a6c0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
a6d0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
a6e0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
a6f0: 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e  een SQLite.** an
a700: 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  d low-level memo
a710: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
a720: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
a730: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  is object is use
a740: 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c  d in only one pl
a750: 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ace in the SQLit
a760: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
a770: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
a780: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
a790: 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61   object is the a
a7a0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73  rgument to.** [s
a7b0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
a7c0: 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67   when the config
a7d0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
a7e0: 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  s.** [SQLITE_CON
a7f0: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b  FIG_MALLOC] or [
a800: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
a810: 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42  TMALLOC].  .** B
a820: 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e  y creating an in
a830: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
a840: 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73  bject.** and pas
a850: 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
a860: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
a870: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
a880: 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f  C]).** during co
a890: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20  nfiguration, an 
a8a0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  application can 
a8b0: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
a8c0: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
a8d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
a8e0: 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65  ystem for SQLite
a8f0: 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20   to use for all 
a900: 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69  of its.** dynami
a910: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
a920: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
a930: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
a940: 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74  h several [built
a950: 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
a960: 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61  ators].** that a
a970: 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  re perfectly ade
a980: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
a990: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
a9a0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
a9b0: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
a9c0: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
a9d0: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
a9e0: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
a9f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
aa00: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
aa10: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
aa20: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
aa30: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
aa40: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
aa50: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
aa60: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
aa70: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
aa80: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
aa90: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
aaa0: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
aab0: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
aac0: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
aad0: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
aae0: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
aaf0: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
ab00: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
ab10: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
ab20: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61  ** The xMalloc a
ab30: 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
ab40: 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
ab50: 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20  the.** malloc() 
ab60: 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
ab70: 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
ab80: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
ab90: 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f  ..** The xReallo
aba0: 63 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f  c method must wo
abb0: 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28  rk like realloc(
abc0: 29 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  ) from the stand
abd0: 61 72 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a  ard C library.**
abe0: 20 77 69 74 68 20 74 68 65 20 65 78 63 65 70 74   with the except
abf0: 69 6f 6e 20 74 68 61 74 20 69 66 20 74 68 65 20  ion that if the 
ac00: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
ac10: 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a  to xRealloc is z
ac20: 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  ero,.** xRealloc
ac30: 20 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70   must be a no-op
ac40: 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70   - it must not p
ac50: 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63  erform any alloc
ac60: 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c  ation or.** deal
ac70: 6c 6f 63 61 74 69 6f 6e 2e 20 20 53 51 4c 69 74  location.  SQLit
ac80: 65 20 67 75 61 72 61 6e 74 65 65 64 73 20 74 68  e guaranteeds th
ac90: 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  at the second ar
aca0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65  gument to.** xRe
acb0: 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20  alloc is always 
acc0: 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  a value returned
acd0: 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c   by a prior call
ace0: 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a   to xRoundup..**
acf0: 20 41 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73   And so in cases
ad00: 20 77 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20   where xRoundup 
ad10: 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
ad20: 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72   positive number
ad30: 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61  ,.** xRealloc ca
ad40: 6e 20 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c  n perform exactl
ad50: 79 20 61 73 20 74 68 65 20 73 74 61 6e 64 61 72  y as the standar
ad60: 64 20 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f  d library reallo
ad70: 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c  c() and.** still
ad80: 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63   be in complianc
ad90: 65 20 77 69 74 68 20 74 68 69 73 20 73 70 65 63  e with this spec
ada0: 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ification..**.**
adb0: 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
adc0: 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
add0: 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
ade0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
adf0: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
ae00: 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
ae10: 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
ae20: 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
ae30: 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
ae40: 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
ae50: 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
ae60: 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
ae70: 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
ae80: 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
ae90: 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
aea0: 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
aeb0: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
aec0: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
aed0: 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
aee0: 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
aef0: 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
af00: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
af10: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
af20: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
af30: 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
af40: 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
af50: 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
af60: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
af70: 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
af80: 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
af90: 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
afa0: 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
afb0: 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
afc0: 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
afd0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
afe0: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
aff0: 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
b000: 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
b010: 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
b020: 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
b030: 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
b040: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
b050: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
b060: 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
b070: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
b080: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
b090: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
b0a0: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a    (For example,.
b0b0: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
b0c0: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
b0d0: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
b0e0: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
b0f0: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
b100: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
b110: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
b120: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
b130: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
b140: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
b150: 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
b160: 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
b170: 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
b180: 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
b190: 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
b1a0: 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
b1b0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
b1c0: 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
b1d0: 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
b1e0: 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
b1f0: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
b200: 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
b210: 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
b220: 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
b230: 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
b240: 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
b250: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
b260: 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
b270: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
b280: 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
b290: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b2a0: 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
b2b0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
b2c0: 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
b2d0: 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
b2e0: 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
b2f0: 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
b300: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
b310: 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
b320: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
b330: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
b340: 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
b350: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
b360: 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
b370: 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
b380: 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
b390: 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
b3a0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
b3b0: 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
b3c0: 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
b3d0: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
b3e0: 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
b3f0: 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
b400: 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
b410: 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
b420: 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
b430: 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
b440: 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
b450: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
b460: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
b470: 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
b480: 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
b490: 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
b4a0: 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
b4b0: 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
b4c0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
b4d0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
b4e0: 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
b4f0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
b500: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
b510: 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
b520: 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
b530: 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
b540: 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
b550: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
b560: 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
b570: 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
b580: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
b590: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
b5a0: 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
b5b0: 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
b5c0: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
b5d0: 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
b5e0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
b5f0: 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
b600: 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
b610: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
b620: 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
b630: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
b640: 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
b650: 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
b660: 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
b670: 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
b680: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
b690: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
b6a0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
b6b0: 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
b6c0: 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
b6d0: 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
b6e0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
b6f0: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
b700: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
b710: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
b720: 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
b730: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
b740: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
b750: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
b760: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48  ation Options {H
b770: 31 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a  10160} <S20000>.
b780: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
b790: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
b7a0: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
b7b0: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
b7c0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
b7d0: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
b7e0: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
b7f0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
b800: 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
b810: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
b820: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
b830: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
b840: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
b850: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
b860: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
b870: 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
b880: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
b890: 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
b8a0: 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
b8b0: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
b8c0: 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
b8d0: 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
b8e0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
b8f0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
b900: 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
b910: 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
b920: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
b930: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
b940: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
b950: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
b960: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
b970: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
b980: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
b990: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
b9a0: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
b9b0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
b9c0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
b9d0: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
b9e0: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
b9f0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
ba00: 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f  ion.  This optio
ba10: 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  n disables.** al
ba20: 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
ba30: 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
ba40: 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
ba50: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
ba60: 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
ba70: 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  thread.</dd>.**.
ba80: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
ba90: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
baa0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
bab0: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
bac0: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
bad0: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e  on.  This option
bae0: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74   disables.** mut
baf0: 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61  exing on [databa
bb00: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
bb10: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
bb20: 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
bb30: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
bb40: 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ion is responsib
bb50: 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69  le for serializi
bb60: 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20  ng access to.** 
bb70: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
bb80: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
bb90: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
bba0: 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74  .  But other mut
bbb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
bbc0: 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69  led so that SQLi
bbd0: 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20  te will be safe 
bbe0: 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74  to use in a mult
bbf0: 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e  i-threaded.** en
bc00: 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e  vironment as lon
bc10: 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65  g as no two thre
bc20: 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75  ads attempt to u
bc30: 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b  se the same.** [
bc40: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
bc50: 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65  ion] at the same
bc60: 20 74 69 6d 65 2e 20 20 53 65 65 20 74 68 65 20   time.  See the 
bc70: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
bc80: 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  .** documentatio
bc90: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
bca0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64   information.</d
bcb0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
bcc0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
bcd0: 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
bce0: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
bcf0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
bd00: 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f   option.  This o
bd10: 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a  ption enables.**
bd20: 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63   all mutexes inc
bd30: 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72  luding the recur
bd40: 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20  sive.** mutexes 
bd50: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
bd60: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
bd70: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
bd80: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e  ] objects..** In
bd90: 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63   this mode (whic
bda0: 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74  h is the default
bdb0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
bdc0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
bdd0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
bde0: 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69  AFE=1]) the SQLi
bdf0: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
be00: 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65  itself serialize
be10: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64   access.** to [d
be20: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
be30: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
be40: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73  ed statements] s
be50: 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70  o that the.** ap
be60: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65  plication is fre
be70: 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  e to use the sam
be80: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
be90: 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a  ection] or the.*
bea0: 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  * same [prepared
beb0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64   statement] in d
bec0: 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73  ifferent threads
bed0: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
bee0: 65 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74  e..** See the [t
bef0: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64  hreading mode] d
bf00: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
bf10: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
bf20: 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  rmation.</dd>.**
bf30: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
bf40: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  ONFIG_MALLOC</dt
bf50: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
bf60: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
bf70: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
bf80: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
bf90: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
bfa0: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
bfb0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
bfc0: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
bfd0: 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
bfe0: 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
bff0: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
c000: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
c010: 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
c020: 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   in place of.** 
c030: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
c040: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62  ation routines b
c050: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
c060: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
c070: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
c080: 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
c090: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
c0a0: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
c0b0: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
c0c0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
c0d0: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
c0e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
c0f0: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
c100: 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
c110: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
c120: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
c130: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
c140: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
c150: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
c160: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
c170: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
c180: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
c190: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
c1a0: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
c1b0: 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
c1c0: 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
c1d0: 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
c1e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c1f0: 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
c200: 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
c210: 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
c220: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
c230: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
c240: 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
c250: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
c260: 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
c270: 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
c280: 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
c290: 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e  as a .** boolean
c2a0: 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
c2b0: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
c2c0: 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65  collection of me
c2d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c2e0: 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20  .** statistics. 
c2f0: 57 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74  When disabled, t
c300: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
c310: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
c320: 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70  ecome .** non-op
c330: 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
c340: 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
c350: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
c360: 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
c370: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
c380: 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
c390: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
c3a0: 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
c3b0: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
c3c0: 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
c3d0: 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c  .**   </ul>.** <
c3e0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
c3f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
c400: 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
c410: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  >This option spe
c420: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
c430: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
c440: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
c450: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
c460: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
c470: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
c480: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
c490: 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
c4a0: 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
c4b0: 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
c4c0: 65 20 73 63 72 61 63 68 20 61 6c 6c 6f 63 61 74  e scrach allocat
c4d0: 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
c4e0: 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
c4f0: 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
c500: 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
c510: 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
c520: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
c530: 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
c540: 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
c550: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
c560: 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
c570: 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61   16. The sz para
c580: 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20  meter should be 
c590: 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c  a few bytes.** l
c5a0: 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 61  arger than the a
c5b0: 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 70  ctual scratch sp
c5c0: 61 63 65 20 72 65 71 75 69 72 65 64 20 64 75 65  ace required due
c5d0: 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20 6f 76 65   to internal ove
c5e0: 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66 69  rhead..** The fi
c5f0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
c600: 75 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  uld pointer to a
c610: 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
c620: 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74   buffer.** of at
c630: 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
c640: 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
c650: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
c660: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  no more than one
c670: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
c680: 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65  at once per thre
c690: 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75  ad, so.** N shou
c6a0: 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65  ld be set to the
c6b0: 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
c6c0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
c6d0: 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  ads.  The sz.** 
c6e0: 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
c6f0: 20 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 20   be 6 times the 
c700: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
c710: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
c720: 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74  e size..** Scrat
c730: 63 68 20 62 75 66 66 65 72 73 20 61 72 65 20 75  ch buffers are u
c740: 73 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  sed as part of t
c750: 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65  he btree balance
c760: 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a   operation.  If.
c770: 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 6c  ** The btree bal
c780: 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 69  ancer needs addi
c790: 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65  tional memory be
c7a0: 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
c7b0: 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61  vided by.** scra
c7c0: 74 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 69  tch buffers or i
c7d0: 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66  f no scratch buf
c7e0: 66 65 72 20 73 70 61 63 65 20 69 73 20 73 70 65  fer space is spe
c7f0: 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c  cified, then SQL
c800: 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b  ite.** goes to [
c810: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
c820: 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  ] to obtain the 
c830: 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e  memory it needs.
c840: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
c850: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
c860: 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
c870: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
c880: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
c890: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
c8a0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
c8b0: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
c8c0: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
c8d0: 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
c8e0: 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20  ault page cache 
c8f0: 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20  implemenation.  
c900: 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
c910: 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f  ration should no
c920: 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20  t be used if an 
c930: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
c940: 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  ne page.** cache
c950: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
c960: 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20  is loaded using 
c970: 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
c980: 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e  G_PCACHE option.
c990: 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
c9a0: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
c9b0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20   this option: A 
c9c0: 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74  pointer to 8-byt
c9d0: 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d  e aligned.** mem
c9e0: 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  ory, the size of
c9f0: 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65   each page buffe
ca00: 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
ca10: 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
ca20: 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
ca30: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
ca40: 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  e the size of th
ca50: 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
ca60: 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f  se page.** (a po
ca70: 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
ca80: 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38  en 512 and 32768
ca90: 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20  ) plus a little 
caa0: 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a  extra for each.*
cab0: 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
cac0: 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20  The page header 
cad0: 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30  size is 20 to 40
cae0: 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67   bytes depending
caf0: 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20   on.** the host 
cb00: 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 49  architecture.  I
cb10: 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
cb20: 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
cb30: 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
cb40: 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74  to make sz a lit
cb50: 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20  tle too large.  
cb60: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
cb70: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
cb80: 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
cb90: 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
cba0: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
cbb0: 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  mory..** SQLite 
cbc0: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
cbd0: 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
cbe0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
cbf0: 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
cc00: 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
cc10: 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
cc20: 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
cc30: 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
cc40: 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
cc50: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
cc60: 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
cc70: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
cc80: 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
cc90: 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
cca0: 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
ccb0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
ccc0: 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
ccd0: 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
cce0: 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
ccf0: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65  tation might use
cd00: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
cd10: 74 68 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f  the N buffers to
cd20: 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79   hold .** memory
cd30: 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f   accounting info
cd40: 72 6d 61 74 69 6f 6e 2e 20 54 68 65 20 70 6f 69  rmation. The poi
cd50: 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  nter in the firs
cd60: 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a  t argument must.
cd70: 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  ** be aligned to
cd80: 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
cd90: 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
cda0: 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
cdb0: 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  Lite.** will be 
cdc0: 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
cdd0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
cde0: 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
cdf0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
ce00: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
ce10: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
ce20: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
ce30: 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f  e will use.** fo
ce40: 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
ce50: 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
ce60: 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79  cation needs bey
ce70: 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
ce80: 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51  ed.** for by [SQ
ce90: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
cea0: 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  TCH] and [SQLITE
ceb0: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
cec0: 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  E]..** There are
ced0: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
cee0: 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  : An 8-byte alig
cef0: 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
cf00: 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
cf10: 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
cf20: 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
cf30: 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
cf40: 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
cf50: 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 49 66 20 74  on size..** If t
cf60: 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
cf70: 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
cf80: 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
cf90: 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
cfa0: 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
cfb0: 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
cfc0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
cfd0: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
cfe0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
cff0: 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
d000: 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
d010: 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
d020: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66  FIG_MALLOC].  If
d030: 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
d040: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
d050: 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
d060: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
d070: 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
d080: 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
d090: 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
d0a0: 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
d0b0: 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
d0c0: 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
d0d0: 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
d0e0: 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
d0f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
d100: 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
d110: 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
d120: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
d130: 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
d140: 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
d150: 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
d160: 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
d170: 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
d180: 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
d190: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
d1a0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
d1b0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
d1c0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
d1d0: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
d1e0: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
d1f0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
d200: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
d210: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
d220: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
d230: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
d240: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
d250: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
d260: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
d270: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
d280: 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ace.** the mutex
d290: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
d2a0: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64  into SQLite.</dd
d2b0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
d2c0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
d2d0: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  EX</dt>.** <dd>T
d2e0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
d2f0: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
d300: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
d310: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
d320: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
d330: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
d340: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
d350: 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
d360: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
d370: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
d380: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
d390: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
d3a0: 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
d3b0: 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  es..** This opti
d3c0: 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
d3d0: 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
d3e0: 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
d3f0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
d400: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
d410: 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
d420: 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
d430: 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
d440: 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
d450: 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
d460: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
d470: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
d480: 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
d490: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
d4a0: 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
d4b0: 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
d4c0: 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
d4d0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
d4e0: 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20  ation lookaside 
d4f0: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54  optimization.  T
d500: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
d510: 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
d520: 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
d530: 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
d540: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
d550: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
d560: 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
d570: 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
d580: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
d590: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
d5a0: 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75   the.** <i>defau
d5b0: 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
d5c0: 20 73 69 7a 65 2e 20 20 54 68 65 20 5b 53 51 4c   size.  The [SQL
d5d0: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
d5e0: 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
d5f0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
d600: 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
d610: 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
d620: 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
d630: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
d640: 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
d650: 65 63 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  ections.</dd>.**
d660: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
d670: 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f 64 74  ONFIG_PCACHE</dt
d680: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
d690: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
d6a0: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
d6b0: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
d6c0: 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65  to.** an [sqlite
d6d0: 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
d6e0: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
d6f0: 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
d700: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
d710: 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  * to a custom pa
d720: 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
d730: 6e 74 61 74 69 6f 6e 2e 20 20 53 51 4c 69 74 65  ntation.  SQLite
d740: 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
d750: 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61   the.** object a
d760: 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70  nd uses it for p
d770: 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
d780: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64   allocations.</d
d790: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
d7a0: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
d7b0: 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
d7c0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
d7d0: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
d7e0: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
d7f0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
d800: 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
d810: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
d820: 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
d830: 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
d840: 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ** page cache im
d850: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
d860: 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 3c 2f  o that object.</
d870: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
d880: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d890: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
d8a0: 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
d8b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d8c0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
d8d0: 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
d8e0: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
d8f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
d900: 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
d910: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
d920: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
d930: 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
d940: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
d950: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
d960: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
d970: 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
d980: 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
d990: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
d9a0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d9b0: 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
d9c0: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
d9d0: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
d9e0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
d9f0: 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
da00: 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
da10: 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
da20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
da30: 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
da40: 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
da50: 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
da60: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
da70: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
da80: 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
da90: 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
daa0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
dab0: 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
dac0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
dad0: 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
dae0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
daf0: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
db00: 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
db10: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
db20: 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
db30: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
db40: 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
db50: 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
db60: 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
db70: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
db80: 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
db90: 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
dba0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
dbb0: 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
dbc0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
dbd0: 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  he_methods* */.#
dbe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
dbf0: 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
dc00: 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33    15  /* sqlite3
dc10: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
dc20: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
dc30: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
dc40: 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31  on Options {H101
dc50: 37 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20  70} <S20000>.** 
dc60: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
dc70: 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
dc80: 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
dc90: 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
dca0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
dcb0: 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
dcc0: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
dcd0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
dce0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
dcf0: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
dd00: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
dd10: 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
dd20: 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
dd30: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
dd40: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
dd50: 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
dd60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
dd70: 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
dd80: 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
dd90: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
dda0: 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
ddb0: 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
ddc0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
ddd0: 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
dde0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
ddf0: 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20  ll worked.  The 
de00: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
de10: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
de20: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
de30: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
de40: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
de50: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
de60: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
de70: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
de80: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
de90: 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
dea0: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
deb0: 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
dec0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
ded0: 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
dee0: 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
def0: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
df00: 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
df10: 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
df20: 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
df30: 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
df40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
df50: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
df60: 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
df70: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
df80: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
df90: 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
dfa0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d 6f  inter to an memo
dfb0: 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
dfc0: 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
dfd0: 65 6d 6f 72 79 2e 0a 2a 2a 20 54 68 65 20 66 69  emory..** The fi
dfe0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 61 79  rst argument may
dff0: 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
e000: 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
e010: 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
e020: 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
e030: 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
e040: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
e050: 28 29 5d 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ()].  The second
e060: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
e070: 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
e080: 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
e090: 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 74  r slot and the t
e0a0: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
e0b0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
e0c0: 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
e0d0: 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
e0e0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
e0f0: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
e100: 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
e110: 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
e120: 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
e130: 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
e140: 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
e150: 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
e160: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
e170: 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
e180: 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   If the second a
e190: 72 67 75 6d 65 6e 74 20 69 73 20 6e 6f 74 0a 2a  rgument is not.*
e1a0: 2a 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  * a multiple of 
e1b0: 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
e1c0: 6c 6c 79 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  lly rounded down
e1d0: 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
e1e0: 6c 6c 65 72 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  ller.** multiple
e1f0: 20 6f 66 20 38 2e 20 20 53 65 65 20 61 6c 73 6f   of 8.  See also
e200: 3a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  : [SQLITE_CONFIG
e210: 5f 4c 4f 4f 4b 41 53 49 44 45 5d 3c 2f 64 64 3e  _LOOKASIDE]</dd>
e220: 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
e230: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
e240: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
e250: 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f  E    1001  /* vo
e260: 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a  id* int int */..
e270: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
e280: 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
e290: 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
e2a0: 6c 74 20 43 6f 64 65 73 20 7b 48 31 32 32 30 30  lt Codes {H12200
e2b0: 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
e2c0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74   The sqlite3_ext
e2d0: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
e2e0: 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
e2f0: 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
e300: 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
e310: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
e320: 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
e330: 65 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  e. The extended 
e340: 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
e350: 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
e360: 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
e370: 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
e380: 6c 69 74 79 20 63 6f 6e 73 69 64 65 72 61 74 69  lity considerati
e390: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ons..**.** Requi
e3a0: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
e3b0: 32 30 31 5d 20 5b 48 31 32 32 30 32 5d 0a 2a 2f  201] [H12202].*/
e3c0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
e3d0: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
e3e0: 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
e3f0: 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
e400: 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
e410: 6e 73 65 72 74 20 52 6f 77 69 64 20 7b 48 31 32  nsert Rowid {H12
e420: 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  220} <S10700>.**
e430: 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69  .** Each entry i
e440: 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
e450: 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
e460: 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
e470: 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
e480: 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
e490: 22 72 6f 77 69 64 22 5d 2e 20 54 68 65 20 72 6f  "rowid"]. The ro
e4a0: 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
e4b0: 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
e4c0: 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
e4d0: 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
e4e0: 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
e4f0: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
e500: 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
e510: 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
e520: 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
e530: 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a  ed columns. If.*
e540: 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
e550: 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
e560: 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
e570: 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
e580: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
e590: 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
e5a0: 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
e5b0: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
e5c0: 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
e5d0: 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  ] of the most re
e5e0: 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
e5f0: 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
e600: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
e610: 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  om the [database
e620: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
e630: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
e640: 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75  ument.  If no su
e650: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
e660: 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  ]s.** have ever 
e670: 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74  occurred on that
e680: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
e690: 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65  tion, zero is re
e6a0: 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  turned..**.** If
e6b0: 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
e6c0: 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
e6d0: 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 5b  gger, then the [
e6e0: 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
e6f0: 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73  serted.** row is
e700: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
e710: 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e  s routine as lon
e720: 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
e730: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
e740: 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69  But once the tri
e750: 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c  gger terminates,
e760: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
e770: 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
e780: 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74  ine.** reverts t
e790: 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65  o the last value
e7a0: 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65   inserted before
e7b0: 20 74 68 65 20 74 72 69 67 67 65 72 20 66 69 72   the trigger fir
e7c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e  ed..**.** An [IN
e7d0: 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
e7e0: 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
e7f0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
e800: 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
e810: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
e820: 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
e830: 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
e840: 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
e850: 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20   routine.  Thus 
e860: 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
e870: 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
e880: 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
e890: 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
e8a0: 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
e8b0: 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
e8c0: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
e8d0: 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
e8e0: 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
e8f0: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
e900: 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20   When INSERT OR 
e910: 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
e920: 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
e930: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
e940: 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
e950: 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
e960: 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
e970: 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
e980: 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
e990: 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
e9a0: 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
e9b0: 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
e9c0: 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
e9d0: 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
e9e0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
e9f0: 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
ea00: 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75  **.** For the pu
ea10: 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
ea20: 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
ea30: 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
ea40: 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
ea50: 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
ea60: 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
ea70: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
ea80: 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
ea90: 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 5d 20 5b 48  :.** [H12221] [H
eaa0: 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20  12223].**.** If 
eab0: 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
eac0: 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
ead0: 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
eae0: 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
eaf0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
eb00: 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
eb10: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
eb20: 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
eb30: 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
eb40: 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
eb50: 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
eb60: 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
eb70: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
eb80: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
eb90: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
eba0: 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
ebb0: 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
ebc0: 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
ebd0: 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
ebe0: 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
ebf0: 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
ec00: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
ec10: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
ec20: 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
ec30: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ec40: 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
ec50: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
ec60: 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20 3c 53  fied {H12240} <S
ec70: 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  10600>.**.** Thi
ec80: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
ec90: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
eca0: 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
ecb0: 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
ecc0: 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
ecd0: 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
ece0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
ecf0: 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
ed00: 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
ed10: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
ed20: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
ed30: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  d by the first p
ed40: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c  arameter..** Onl
ed50: 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
ed60: 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
ed70: 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
ed80: 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
ed90: 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
eda0: 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
edb0: 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
edc0: 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
edd0: 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
ede0: 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
edf0: 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
ee00: 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74 68   counted. Use th
ee10: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f  e.** [sqlite3_to
ee20: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
ee30: 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20  unction to find 
ee40: 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
ee50: 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69   of changes.** i
ee60: 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
ee70: 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
ee80: 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20  ers and foreign 
ee90: 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  key actions..**.
eea0: 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
eeb0: 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69  view that are si
eec0: 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49  mulated by an [I
eed0: 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
eee0: 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  r].** are not co
eef0: 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61  unted.  Only rea
ef00: 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20  l table changes 
ef10: 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
ef20: 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65  ** A "row change
ef30: 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
ef40: 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
ef50: 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
ef60: 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
ef70: 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
ef80: 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
ef90: 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
efa0: 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
efb0: 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
efc0: 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
efd0: 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
efe0: 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
eff0: 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
f000: 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
f010: 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
f020: 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
f030: 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
f040: 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
f050: 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ..**.** A "trigg
f060: 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
f070: 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
f080: 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
f090: 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
f0a0: 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
f0b0: 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
f0c0: 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
f0d0: 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
f0e0: 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
f0f0: 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
f100: 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
f110: 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
f120: 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
f130: 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
f140: 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
f150: 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
f160: 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
f170: 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
f180: 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
f190: 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
f1a0: 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
f1b0: 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
f1c0: 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
f1d0: 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
f1e0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e  on..**.** Callin
f1f0: 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  g [sqlite3_exec(
f200: 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  )] or [sqlite3_s
f210: 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65  tep()] recursive
f220: 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63  ly does.** not c
f230: 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67  reate a new trig
f240: 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
f250: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
f260: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
f270: 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f  ber of direct ro
f280: 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  w changes in the
f290: 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
f2a0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
f2b0: 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
f2c0: 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
f2d0: 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  ame.** trigger c
f2e0: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  ontext..**.** Th
f2f0: 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20  us, when called 
f300: 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
f310: 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  el, this functio
f320: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  n returns the.**
f330: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
f340: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
f350: 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
f360: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
f370: 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63  ** that also occ
f380: 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70  urred at the top
f390: 20 6c 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20   level.  Within 
f3a0: 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72  the body of a tr
f3b0: 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71  igger,.** the sq
f3c0: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
f3d0: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
f3e0: 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20   called to find 
f3f0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
f400: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
f410: 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
f420: 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
f430: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
f440: 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77  E.** statement w
f450: 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
f460: 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  f the same trigg
f470: 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  er..** However, 
f480: 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72  the number retur
f490: 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
f4a0: 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20  lude changes.** 
f4b0: 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69  caused by subtri
f4c0: 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73  ggers since thos
f4d0: 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e  e have their own
f4e0: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
f4f0: 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
f500: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
f510: 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
f520: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75   and the.** [cou
f530: 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
f540: 61 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  a]..**.** Requir
f550: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32  ements:.** [H122
f560: 34 31 5d 20 5b 48 31 32 32 34 33 5d 0a 2a 2a 0a  41] [H12243].**.
f570: 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
f580: 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
f590: 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
f5a0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
f5b0: 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
f5c0: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
f5d0: 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
f5e0: 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
f5f0: 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
f600: 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
f610: 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
f620: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
f630: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
f640: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f650: 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
f660: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b   Rows Modified {
f670: 48 31 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e  H12260} <S10600>
f680: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
f690: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
f6a0: 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63   number of row c
f6b0: 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
f6c0: 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55   [INSERT],.** [U
f6d0: 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
f6e0: 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  E] statements si
f6f0: 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  nce the [databas
f700: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61  e connection] wa
f710: 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65  s opened..** The
f720: 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20   count includes 
f730: 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d  all changes from
f740: 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49   all [CREATE TRI
f750: 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20  GGER | trigger] 
f760: 0a 2a 2a 20 63 6f 6e 74 65 78 74 73 20 61 6e 64  .** contexts and
f770: 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79   changes made by
f780: 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
f790: 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c  tions]. However,
f7a0: 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f  .** the count do
f7b0: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
f7c0: 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69  hanges used to i
f7d0: 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43  mplement [REPLAC
f7e0: 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a  E] constraints,.
f7f0: 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20  ** do rollbacks 
f800: 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  or ABORT process
f810: 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41  ing, or [DROP TA
f820: 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e  BLE] processing.
f830: 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64    The.** count d
f840: 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
f850: 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68  rows of views th
f860: 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54  at fire an [INST
f870: 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c  EAD OF trigger],
f880: 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68  .** though if th
f890: 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  e INSTEAD OF tri
f8a0: 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67  gger makes chang
f8b0: 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74  es of its own, t
f8c0: 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a  hose changes .**
f8d0: 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
f8e0: 20 54 68 65 20 63 68 61 6e 67 65 73 20 61 72 65   The changes are
f8f0: 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e   counted as soon
f900: 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
f910: 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  t that makes the
f920: 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  m is.** complete
f930: 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74  d (when the stat
f940: 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20  ement handle is 
f950: 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
f960: 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
f970: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
f980: 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  ize()])..**.** S
f990: 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
f9a0: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
f9b0: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 74 68  interface and th
f9c0: 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
f9d0: 67 65 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2a 0a  ges pragma]..**.
f9e0: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
f9f0: 0a 2a 2a 20 5b 48 31 32 32 36 31 5d 20 5b 48 31  .** [H12261] [H1
fa00: 32 32 36 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61  2263].**.** If a
fa10: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
fa20: 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
fa30: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
fa40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
fa50: 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
fa60: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
fa70: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
fa80: 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  n the value.** r
fa90: 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
faa0: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
fab0: 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
fac0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
fad0: 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
fae0: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
faf0: 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
fb00: 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
fb10: 75 65 72 79 20 7b 48 31 32 32 37 30 7d 20 3c 53  uery {H12270} <S
fb20: 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  30500>.**.** Thi
fb30: 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
fb40: 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61  s any pending da
fb50: 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
fb60: 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a   to abort and.**
fb70: 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65   return at its e
fb80: 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e  arliest opportun
fb90: 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  ity. This routin
fba0: 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
fbb0: 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
fbc0: 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
fbd0: 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
fbe0: 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
fbf0: 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
fc00: 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
fc10: 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
fc20: 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
fc30: 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
fc40: 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66  .**.** It is saf
fc50: 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
fc60: 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
fc70: 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
fc80: 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
fc90: 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
fca0: 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
fcb0: 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
fcc0: 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
fcd0: 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
fce0: 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
fcf0: 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
fd00: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
fd10: 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
fd20: 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
fd30: 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
fd40: 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
fd50: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51  ..**.** If an SQ
fd60: 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
fd70: 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
fd80: 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
fd90: 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
fda0: 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
fdb0: 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
fdc0: 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
fdd0: 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
fde0: 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
fdf0: 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
fe00: 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
fe10: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c  on..**.** An SQL
fe20: 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
fe30: 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
fe40: 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
fe50: 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
fe60: 2a 20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75  * If the interru
fe70: 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
fe80: 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
fe90: 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
fea0: 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
feb0: 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
fec0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
fed0: 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
fee0: 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
fef0: 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
ff00: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
ff10: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
ff20: 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
ff30: 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
ff40: 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
ff50: 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
ff60: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
ff70: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
ff80: 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
ff90: 74 65 2e 20 20 41 6e 79 20 6e 65 77 20 53 51 4c  te.  Any new SQL
ffa0: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
ffb0: 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
ffc0: 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
ffd0: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
ffe0: 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
fff0: 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
10000 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
10010 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
10020 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
10030 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
10040 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
10050 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
10060 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 4e 65 77  upt() call.  New
10070 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
10080 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
10090 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
100a0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
100b0 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
100c0 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
100d0 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
100e0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
100f0 29 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  )..** A call to 
10100 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
10110 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
10120 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
10130 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
10140 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
10150 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
10160 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
10170 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
10180 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
10190 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
101a0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
101b0 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
101c0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
101d0 2a 2a 20 5b 48 31 32 32 37 31 5d 20 5b 48 31 32  ** [H12271] [H12
101e0 32 37 32 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  272].**.** If th
101f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
10200 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
10210 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
10220 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
10230 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
10240 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
10250 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
10260 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
10270 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
10280 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10290 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
102a0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
102b0 73 20 43 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35  s Complete {H105
102c0 31 30 7d 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a  10} <S70200>.**.
102d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
102e0 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
102f0 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
10300 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
10310 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
10320 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
10330 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
10340 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
10350 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
10360 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
10370 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
10380 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
10390 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
103a0 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
103b0 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ng.  These routi
103c0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
103d0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
103e0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
103f0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
10400 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73   statement.  A s
10410 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
10420 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
10430 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
10440 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
10450 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
10460 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
10470 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
10480 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
10490 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f  atement.  Semico
104a0 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
104b0 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
104c0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
104d0 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
104e0 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
104f0 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
10500 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
10510 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
10520 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
10530 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
10540 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
10550 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
10560 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
10570 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
10580 2e 20 20 57 68 69 74 65 73 70 61 63 65 0a 2a 2a  .  Whitespace.**
10590 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68   and comments th
105a0 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69  at follow the fi
105b0 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72  nal semicolon ar
105c0 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  e ignored..**.**
105d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
105e0 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
105f0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
10600 6f 6d 70 6c 65 74 65 2e 20 20 49 66 20 61 0a 2a  omplete.  If a.*
10610 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
10620 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
10630 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
10640 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
10650 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
10660 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
10670 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
10680 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
10690 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
106a0 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
106b0 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c  QL..**.** If SQL
106c0 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
106d0 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
106e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
106f0 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
10700 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
10710 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
10720 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
10730 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
10740 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
10750 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
10760 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
10770 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
10780 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
10790 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
107a0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
107b0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
107c0 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
107d0 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
107e0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
107f0 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
10800 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
10810 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
10820 65 6e 74 73 3a 20 5b 48 31 30 35 31 31 5d 20 5b  ents: [H10511] [
10830 48 31 30 35 31 32 5d 0a 2a 2a 0a 2a 2a 20 54 68  H10512].**.** Th
10840 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
10850 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
10860 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
10870 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
10880 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
10890 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
108a0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
108b0 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
108c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
108d0 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
108e0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
108f0 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
10900 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
10910 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
10920 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
10930 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
10940 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
10950 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
10960 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
10970 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
10980 55 53 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33  USY Errors {H123
10990 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a  10} <S40400>.**.
109a0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
109b0 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
109c0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
109d0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
109e0 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
109f0 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
10a00 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
10a10 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
10a20 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
10a30 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
10a40 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ked..**.** If th
10a50 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
10a60 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
10a70 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
10a80 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
10a90 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75  CKED].** is retu
10aa0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
10ab0 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
10ac0 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20  ng the lock. If 
10ad0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
10ae0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
10af0 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
10b00 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f  ack will be invo
10b10 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
10b20 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  uments..**.** Th
10b30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10b40 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20   to the handler 
10b50 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
10b60 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
10b70 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
10b80 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
10b90 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
10ba0 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65  ndler().  The se
10bb0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
10bc0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
10bd0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
10be0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
10bf0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
10c00 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
10c10 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
10c20 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
10c30 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73  .  If the.** bus
10c40 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
10c50 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
10c60 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
10c70 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
10c80 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
10c90 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
10ca0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
10cb0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
10cc0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
10cd0 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
10ce0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
10cf0 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
10d00 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
10d10 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  de to open the d
10d20 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
10d30 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
10d40 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
10d50 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
10d60 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
10d70 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
10d80 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
10d90 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
10da0 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
10db0 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20   contention. If 
10dc0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
10dd0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
10de0 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
10df0 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
10e00 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
10e10 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
10e20 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
10e30 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
10e40 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
10e50 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
10e60 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
10e70 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
10e80 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
10e90 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
10ea0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
10eb0 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
10ec0 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
10ed0 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
10ee0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
10ef0 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
10f00 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
10f10 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
10f20 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
10f30 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
10f40 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
10f50 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
10f60 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
10f70 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
10f80 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
10f90 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
10fa0 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
10fb0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
10fc0 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
10fd0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
10fe0 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
10ff0 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
11000 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
11010 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
11020 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
11030 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
11040 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
11050 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
11060 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
11070 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
11080 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
11090 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
110a0 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
110b0 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
110c0 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
110d0 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
110e0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
110f0 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  proceed..**.** T
11100 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
11110 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
11120 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
11130 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20  ITE_BUSY] error 
11140 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  is converted to 
11150 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
11160 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53  OCKED].** when S
11170 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20  QLite is in the 
11180 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67  middle of a larg
11190 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68  e transaction wh
111a0 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63  ere all the.** c
111b0 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20  hanges will not 
111c0 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d  fit into the in-
111d0 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53  memory cache.  S
111e0 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c  QLite will.** al
111f0 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53  ready hold a RES
11200 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68  ERVED lock on th
11210 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
11220 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a   but it needs.**
11230 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73   to promote this
11240 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49   lock to EXCLUSI
11250 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61  VE so that it ca
11260 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a  n spill cache.**
11270 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20   pages into the 
11280 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
11290 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f  thout harm to co
112a0 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64  ncurrent.** read
112b0 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 20 75  ers.  If it is u
112c0 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
112d0 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
112e0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
112f0 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
11300 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
11310 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
11320 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
11330 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
11340 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
11350 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
11360 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
11370 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
11380 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
11390 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65  LOCKED].  This e
113a0 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74  rror code promot
113b0 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e  ion.** forces an
113c0 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62   automatic rollb
113d0 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67  ack of the chang
113e0 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  es.  See the.** 
113f0 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61  <a href="/cvstra
11400 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
11410 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
11420 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
11430 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
11440 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
11450 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
11460 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
11470 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
11480 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  nt..**.** There 
11490 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
114a0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
114b0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
114c0 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
114d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
114e0 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
114f0 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
11500 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
11510 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20  y set handler.  
11520 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
11530 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
11540 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
11550 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
11560 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
11570 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
11580 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
11590 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
115a0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
115b0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
115c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
115d0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
115e0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
115f0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
11600 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
11610 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
11620 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 52 65 71 75  ior..** .** Requ
11630 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
11640 32 33 31 31 5d 20 5b 48 31 32 33 31 32 5d 20 5b  2311] [H12312] [
11650 48 31 32 33 31 34 5d 20 5b 48 31 32 33 31 36 5d  H12314] [H12316]
11660 20 5b 48 31 32 33 31 38 5d 0a 2a 2a 0a 2a 2a 20   [H12318].**.** 
11670 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
11680 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
11690 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
116a0 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
116b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
116c0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
116d0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
116e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
116f0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
11700 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
11710 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
11720 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11730 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
11740 65 6f 75 74 20 7b 48 31 32 33 34 30 7d 20 3c 53  eout {H12340} <S
11750 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  40410>.**.** Thi
11760 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
11770 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
11780 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
11790 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
117a0 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
117b0 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
117c0 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
117d0 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68  e is locked.  Th
117e0 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
117f0 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
11800 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
11810 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
11820 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
11830 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
11840 6d 75 6c 61 74 65 64 2e 20 7b 48 31 32 33 34 33  mulated. {H12343
11850 7d 20 41 66 74 65 72 20 22 6d 73 22 20 6d 69 6c  } After "ms" mil
11860 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
11870 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
11880 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
11890 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
118a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
118b0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
118c0 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
118d0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
118e0 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e  D]..**.** Callin
118f0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
11900 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
11910 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
11920 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
11930 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
11940 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
11950 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20   There can only 
11960 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
11970 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
11980 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
11990 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
119a0 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e  n] any any given
119b0 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
119c0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
119d0 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
119e0 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
119f0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
11a00 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
11a10 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
11a20 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
11a30 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
11a40 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  cleared..**.** R
11a50 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
11a60 5b 48 31 32 33 34 31 5d 20 5b 48 31 32 33 34 33  [H12341] [H12343
11a70 5d 20 5b 48 31 32 33 34 34 5d 0a 2a 2f 0a 69 6e  ] [H12344].*/.in
11a80 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
11a90 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
11aa0 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
11ab0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
11ac0 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
11ad0 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
11ae0 69 65 73 20 7b 48 31 32 33 37 30 7d 20 3c 53 31  ies {H12370} <S1
11af0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  0000>.**.** Defi
11b00 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
11b10 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
11b20 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
11b30 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
11b40 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
11b50 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
11b60 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
11b70 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
11b80 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
11b90 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
11ba0 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
11bb0 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
11bc0 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
11bd0 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
11be0 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
11bf0 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
11c00 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
11c10 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
11c20 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
11c30 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
11c40 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
11c50 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
11c60 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
11c70 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
11c80 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
11c90 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
11ca0 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
11cb0 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
11cc0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
11cd0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
11ce0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
11cf0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
11d00 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
11d10 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
11d20 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
11d30 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
11d40 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
11d50 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
11d60 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
11d70 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
11d80 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
11d90 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
11da0 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
11db0 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
11dc0 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
11dd0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
11de0 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
11df0 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
11e00 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
11e10 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
11e20 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
11e30 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
11e40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
11e50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
11e60 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
11e70 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
11e80 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
11e90 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
11ea0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
11eb0 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
11ec0 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
11ed0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
11ee0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
11ef0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
11f00 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
11f10 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
11f20 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  le()]..**.** As 
11f30 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
11f40 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
11f50 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
11f60 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
11f70 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
11f80 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
11f90 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
11fa0 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
11fb0 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
11fc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
11fd0 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
11fe0 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
11ff0 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
12000 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
12010 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
12020 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
12030 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
12040 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
12050 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
12060 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
12070 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
12080 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
12090 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
120a0 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
120b0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
120c0 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
120d0 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
120e0 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
120f0 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
12100 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
12110 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
12120 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
12130 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
12140 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
12150 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
12160 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
12170 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
12180 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
12190 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
121a0 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
121b0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
121c0 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
121d0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
121e0 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
121f0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
12200 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
12210 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
12220 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
12230 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
12240 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
12250 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
12260 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
12270 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
12280 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
12290 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
122a0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
122b0 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
122c0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
122d0 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
122e0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
122f0 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  It returns a res
12300 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
12310 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
12320 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
12330 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
12340 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ter the calling 
12350 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e  function has fin
12360 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20  ished using the 
12370 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c  result, it shoul
12380 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70 6f  d.** pass the po
12390 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65 73  inter to the res
123a0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71 6c  ult table to sql
123b0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
123c0 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
123d0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
123e0 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
123f0 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
12400 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
12410 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
12420 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
12430 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
12440 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
12450 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
12460 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
12470 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
12480 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
12490 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
124a0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
124b0 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
124c0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
124d0 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
124e0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
124f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
12500 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
12510 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
12520 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
12530 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
12540 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
12550 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
12560 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
12570 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
12580 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
12590 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
125a0 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
125b0 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
125c0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
125d0 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
125e0 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
125f0 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
12600 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
12610 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
12620 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
12630 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
12640 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
12650 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
12660 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
12670 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
12680 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ode()] or [sqlit
12690 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
126a0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
126b0 3a 0a 2a 2a 20 5b 48 31 32 33 37 31 5d 20 5b 48  :.** [H12371] [H
126c0 31 32 33 37 33 5d 20 5b 48 31 32 33 37 34 5d 20  12373] [H12374] 
126d0 5b 48 31 32 33 37 36 5d 20 5b 48 31 32 33 37 39  [H12376] [H12379
126e0 5d 20 5b 48 31 32 33 38 32 5d 0a 2a 2f 0a 69 6e  ] [H12382].*/.in
126f0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
12700 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
12710 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
12720 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
12730 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
12740 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
12750 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
12760 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
12770 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
12780 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
12790 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
127a0 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
127b0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
127c0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
127d0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
127e0 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
127f0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
12800 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
12810 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
12820 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
12830 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
12840 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
12850 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
12860 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
12870 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
12880 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
12890 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
128a0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
128b0 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c 53 37 30  ns {H17400} <S70
128c0 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a  000><S20000>.**.
128d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
128e0 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
128f0 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
12900 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
12910 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
12920 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
12930 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  ibrary..**.** Th
12940 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
12950 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
12960 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
12970 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
12980 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
12990 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
129a0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
129b0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
129c0 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
129d0 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
129e0 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
129f0 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
12a00 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
12a10 2e 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73  .  Both routines
12a20 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
12a30 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
12a40 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
12a50 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
12a60 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
12a70 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
12a80 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
12a90 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71  ing..**.** In sq
12aa0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
12ab0 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
12ac0 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
12ad0 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
12ae0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
12af0 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
12b00 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
12b10 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
12b20 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
12b30 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
12b40 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
12b50 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
12b60 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
12b70 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
12b80 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
12b90 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
12ba0 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
12bb0 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54  m snprintf().  T
12bc0 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
12bd0 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
12be0 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
12bf0 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
12c00 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
12c10 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
12c20 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68  y.  Note also th
12c30 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
12c40 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
12c50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
12c60 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
12c70 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
12c80 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
12c90 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
12ca0 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
12cb0 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  .  We admit that
12cc0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
12cd0 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
12ce0 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
12cf0 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
12d00 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
12d10 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
12d20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
12d30 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
12d40 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
12d50 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
12d60 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
12d70 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61  .**.** As long a
12d80 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
12d90 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
12da0 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
12db0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
12dc0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
12dd0 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
12de0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
12df0 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ed.  The first.*
12e00 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
12e10 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
12e20 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
12e30 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
12e40 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
12e50 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
12e60 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
12e70 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
12e80 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
12e90 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
12ea0 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
12eb0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
12ec0 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
12ed0 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
12ee0 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
12ef0 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
12f00 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
12f10 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
12f20 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
12f30 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
12f40 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
12f50 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
12f60 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
12f70 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
12f80 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
12f90 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
12fa0 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77   The %q option w
12fb0 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
12fc0 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
12fd0 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69  tes a null-termi
12fe0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
12ff0 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
13000 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
13010 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
13020 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
13030 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
13040 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
13050 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
13060 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69  eral.  By doubli
13070 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
13080 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
13090 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
130a0 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
130b0 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
130c0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
130d0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
130e0 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
130f0 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
13100 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
13110 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
13120 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
13130 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
13140 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
13150 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
13160 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
13170 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
13180 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
13190 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
131a0 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
131b0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
131c0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
131d0 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
131e0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
131f0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
13200 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
13210 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
13220 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
13230 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
13240 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
13250 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
13260 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
13270 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
13280 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
13290 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
132a0 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
132b0 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
132c0 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
132d0 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
132e0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
132f0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
13300 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
13310 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
13320 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
13330 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
13340 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
13350 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
13360 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
13370 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
13380 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
13390 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
133a0 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
133b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
133c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
133d0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
133e0 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
133f0 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
13400 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
13410 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
13420 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
13430 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
13440 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
13450 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
13460 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
13470 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
13480 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
13490 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
134a0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
134b0 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69  *.** The %Q opti
134c0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
134d0 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
134e0 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
134f0 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
13500 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
13510 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
13520 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
13530 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
13540 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
13550 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
13560 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
13570 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
13580 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
13590 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
135a0 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  s) in place of t
135b0 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53  he %Q option.  S
135c0 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
135d0 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
135e0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
135f0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
13600 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
13610 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
13620 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
13630 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
13640 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
13650 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
13660 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
13670 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
13680 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13690 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
136a0 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
136b0 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
136c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
136d0 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
136e0 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
136f0 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
13700 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
13710 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a  r..**.** The "%z
13720 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
13730 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c  ion works exactl
13740 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68  y like "%s" with
13750 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
13760 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
13770 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
13780 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
13790 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
137a0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
137b0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
137c0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
137d0 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ng. {END}.**.** 
137e0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
137f0 20 5b 48 31 37 34 30 33 5d 20 5b 48 31 37 34 30   [H17403] [H1740
13800 36 5d 20 5b 48 31 37 34 30 37 5d 0a 2a 2f 0a 63  6] [H17407].*/.c
13810 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
13820 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
13830 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
13840 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
13850 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
13860 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
13870 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
13880 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
13890 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, ...);../*.** 
138a0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
138b0 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
138c0 79 73 74 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c  ystem {H17300} <
138d0 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20000>.**.** Th
138e0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75  e SQLite core  u
138f0 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
13900 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
13910 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
13920 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
13930 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
13940 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
13950 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
13960 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
13970 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
13980 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
13990 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
139a0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
139b0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
139c0 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
139d0 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
139e0 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
139f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61  * The sqlite3_ma
13a00 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
13a10 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
13a20 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
13a30 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
13a40 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
13a50 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
13a60 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
13a70 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * If sqlite3_mal
13a80 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
13a90 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
13aa0 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
13ab0 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
13ac0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
13ad0 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
13ae0 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
13af0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
13b00 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
13b10 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
13b20 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
13b30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
13b40 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71  **.** Calling sq
13b50 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
13b60 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
13b70 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
13b80 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
13b90 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
13ba0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
13bb0 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
13bc0 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
13bd0 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
13be0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65   The sqlite3_fre
13bf0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
13c00 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
13c10 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
13c20 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
13c30 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
13c40 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
13c50 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
13c60 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
13c70 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
13c80 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
13c90 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
13ca0 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
13cb0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
13cc0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
13cd0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
13ce0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
13cf0 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
13d00 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
13d10 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
13d20 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
13d30 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
13d40 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
13d50 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
13d60 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
13d70 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
13d80 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
13d90 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
13da0 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
13db0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
13dc0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
13dd0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  lloc()..**.** Th
13de0 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
13df0 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
13e00 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
13e10 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
13e20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
13e30 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
13e40 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
13e50 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
13e60 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
13e70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13e80 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
13e90 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
13ea0 61 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68  arameter.  If th
13eb0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
13ec0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
13ed0 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e  lloc().** is a N
13ee0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
13ef0 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
13f00 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
13f10 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
13f20 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65  _malloc(N) where
13f30 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
13f40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
13f50 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
13f60 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e  .** If the secon
13f70 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
13f80 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
13f90 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
13fa0 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
13fb0 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
13fc0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
13fd0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
13fe0 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
13ff0 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
14000 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
14010 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
14020 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
14030 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20  loc() returns a 
14040 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
14050 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
14060 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
14070 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
14080 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69   NULL if suffici
14090 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e  ent memory is un
140a0 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66  available..** If
140b0 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
140c0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
140d0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
140e0 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
140f0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
14100 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
14110 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
14120 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
14130 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
14140 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
14150 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
14160 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
14170 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  d..** If sqlite3
14180 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
14190 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
141a0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
141b0 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
141c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65  ed..**.** The me
141d0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
141e0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
141f0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
14200 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
14210 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
14220 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
14230 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e  te boundary. {EN
14240 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66  D}.**.** The def
14250 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ault implementat
14260 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72  ion of the memor
14270 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
14280 73 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74  system uses.** t
14290 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  he malloc(), rea
142a0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
142b0 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  ) provided by th
142c0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
142d0 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32  rary..** {H17382
142e0 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51  } However, if SQ
142f0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
14300 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
14310 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d  ITE_MEMORY_SIZE=
14320 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65  <i>NNN</i> C pre
14330 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
14340 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69  (where <i>NNN</i
14350 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67  >.** is an integ
14360 65 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  er), then SQLite
14370 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69 63   create a static
14380 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61   array of at lea
14390 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e  st.** <i>NNN</i>
143a0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
143b0 6e 64 20 75 73 65 73 20 74 68 61 74 20 61 72 72  nd uses that arr
143c0 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ay for all of it
143d0 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d  s dynamic.** mem
143e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
143f0 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64  eeds. {END}  Add
14400 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  itional memory a
14410 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73  llocator options
14420 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65 64  .** may be added
14430 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
14440 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  ses..**.** In SQ
14450 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
14460 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
14470 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
14480 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
14490 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
144a0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
144b0 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
144c0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
144d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
144e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
144f0 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
14500 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
14510 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
14520 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
14530 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
14540 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
14550 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  e used..**.** Th
14560 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
14570 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
14580 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ls.** the system
14590 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
145a0 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
145b0 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
145c0 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
145d0 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
145e0 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
145f0 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
14600 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
14610 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
14620 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
14630 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
14640 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
14650 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
14660 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ors are detected
14670 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72  , but.** they ar
14680 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
14690 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
146a0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
146b0 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
146c0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
146d0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  MEM]..**.** Requ
146e0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
146f0 37 33 30 33 5d 20 5b 48 31 37 33 30 34 5d 20 5b  7303] [H17304] [
14700 48 31 37 33 30 35 5d 20 5b 48 31 37 33 30 36 5d  H17305] [H17306]
14710 20 5b 48 31 37 33 31 30 5d 20 5b 48 31 37 33 31   [H17310] [H1731
14720 32 5d 20 5b 48 31 37 33 31 35 5d 20 5b 48 31 37  2] [H17315] [H17
14730 33 31 38 5d 0a 2a 2a 20 5b 48 31 37 33 32 31 5d  318].** [H17321]
14740 20 5b 48 31 37 33 32 32 5d 20 5b 48 31 37 33 32   [H17322] [H1732
14750 33 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  3].**.** The poi
14760 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
14770 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
14780 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
14790 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
147a0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
147b0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
147c0 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
147d0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
147e0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
147f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
14800 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
14810 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
14820 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
14830 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
14840 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
14850 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
14860 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
14870 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
14880 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
14890 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
148a0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
148b0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
148c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
148d0 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
148e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
148f0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
14900 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
14910 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
14920 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
14930 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
14940 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
14950 53 74 61 74 69 73 74 69 63 73 20 7b 48 31 37 33  Statistics {H173
14960 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a  70} <S30210>.**.
14970 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
14980 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
14990 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
149a0 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
149b0 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
149c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
149d0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
149e0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
149f0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
14a00 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
14a10 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
14a20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14a30 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
14a40 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
14a50 3a 0a 2a 2a 20 5b 48 31 37 33 37 31 5d 20 5b 48  :.** [H17371] [H
14a60 31 37 33 37 33 5d 20 5b 48 31 37 33 37 34 5d 20  17373] [H17374] 
14a70 5b 48 31 37 33 37 35 5d 0a 2a 2f 0a 73 71 6c 69  [H17375].*/.sqli
14a80 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
14a90 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
14aa0 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
14ab0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
14ac0 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
14ad0 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
14ae0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
14af0 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
14b00 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 48 31 37  r Generator {H17
14b10 33 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a  390} <S20000>.**
14b20 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
14b30 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
14b40 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
14b50 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
14b60 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
14b70 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
14b80 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
14b90 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
14ba0 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
14bb0 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
14bc0 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
14bd0 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
14be0 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
14bf0 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
14c00 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
14c10 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
14c20 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
14c30 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
14c40 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
14c50 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
14c60 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
14c70 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
14c80 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
14c90 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  ses..**.** A cal
14ca0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
14cb0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
14cc0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
14cd0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
14ce0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69  .** The first ti
14cf0 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
14d00 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
14d10 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
14d20 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
14d30 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
14d40 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
14d50 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
14d60 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
14d70 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
14d80 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
14d90 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
14da0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61   object..** On a
14db0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
14dc0 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70  vocations, the p
14dd0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
14de0 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
14df0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
14e00 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
14e10 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
14e20 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
14e30 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a  s.** method..**.
14e40 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
14e50 0a 2a 2a 20 5b 48 31 37 33 39 32 5d 0a 2a 2f 0a  .** [H17392].*/.
14e60 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
14e70 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
14e80 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
14e90 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
14ea0 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
14eb0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b  tion Callbacks {
14ec0 48 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30 3e  H12500} <S70100>
14ed0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
14ee0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ine registers a 
14ef0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
14f00 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
14f10 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
14f20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
14f30 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
14f40 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
14f50 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
14f60 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
14f70 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
14f80 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
14f90 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
14fa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
14fb0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
14fc0 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
14fd0 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
14fe0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
14ff0 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
15000 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
15010 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a  )].  At various.
15020 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
15030 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
15040 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
15050 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
15060 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
15070 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
15080 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
15090 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
150a0 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
150b0 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
150c0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54   are allowed.  T
150d0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
150e0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
150f0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
15100 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
15110 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
15120 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
15130 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
15140 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
15150 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
15160 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
15170 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
15180 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
15190 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
151a0 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
151b0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
151c0 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
151d0 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 74   an error.  If t
151e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
151f0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
15200 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
15210 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
15220 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
15230 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
15240 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
15250 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
15260 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
15270 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
15280 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
15290 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
152a0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
152b0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
152c0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
152d0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
152e0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
152f0 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
15300 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
15310 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68   is ok.  When th
15320 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
15330 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
15340 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
15350 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
15360 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
15370 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
15380 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
15390 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
153a0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
153b0 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
153c0 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
153d0 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
153e0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
153f0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
15400 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
15410 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
15420 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
15430 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
15440 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
15450 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 54 68  () interface. Th
15460 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15470 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
15480 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
15490 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
154a0 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
154b0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
154c0 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
154d0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
154e0 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68  thorized. The th
154f0 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
15500 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
15510 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
15520 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
15530 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
15540 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
15550 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
15560 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
15570 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
15580 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 61  ..**.** If the a
15590 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
155a0 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
155b0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
155c0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
155d0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
155e0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
155f0 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
15600 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
15610 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
15620 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
15630 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
15640 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
15650 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
15660 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
15670 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
15680 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
15690 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
156a0 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
156b0 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
156c0 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
156d0 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
156e0 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
156f0 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
15700 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
15710 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
15720 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
15730 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
15740 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
15750 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
15760 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
15770 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
15780 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
15790 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
157a0 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
157b0 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
157c0 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
157d0 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
157e0 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
157f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
15800 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
15810 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
15820 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
15830 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
15840 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
15850 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
15860 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
15870 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
15880 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
15890 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
158a0 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
158b0 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
158c0 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
158d0 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
158e0 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
158f0 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
15900 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
15910 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
15920 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
15930 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
15940 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
15950 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
15960 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
15970 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
15980 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
15990 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
159a0 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
159b0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
159c0 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
159d0 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
159e0 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
159f0 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
15a00 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
15a10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
15a20 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
15a30 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
15a40 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
15a50 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
15a60 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
15a70 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
15a80 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
15a90 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
15aa0 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
15ab0 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
15ac0 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
15ad0 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
15ae0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
15af0 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
15b00 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
15b10 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
15b20 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
15b30 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
15b40 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
15b50 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
15b60 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  ** Only a single
15b70 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
15b80 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
15b90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15ba0 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
15bb0 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
15bc0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
15bd0 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
15be0 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
15bf0 73 20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65  s call.  Disable
15c00 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
15c10 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
15c20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
15c30 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
15c40 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
15c50 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
15c60 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
15c70 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
15c80 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
15c90 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
15ca0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
15cb0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
15cc0 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
15cd0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
15ce0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
15cf0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
15d00 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
15d10 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
15d20 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
15d30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
15d40 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
15d50 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
15d60 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
15d70 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73 71 6c 69  **.** When [sqli
15d80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
15d90 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
15da0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
15db0 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
15dc0 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
15dd0 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
15de0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
15df0 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
15e00 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
15e10 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
15e20 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
15e30 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
15e40 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
15e50 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
15e60 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
15e70 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
15e80 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  tep()]..**.** No
15e90 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
15ea0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
15eb0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
15ec0 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
15ed0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
15ee0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
15ef0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
15f00 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
15f10 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
15f20 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
15f30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
15f40 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20  ], unless.** as 
15f50 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72  stated in the pr
15f60 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
15f70 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
15f80 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69   invokes.** sqli
15f90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
15fa0 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20   to reprepare a 
15fb0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
15fc0 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  a schema change.
15fd0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
15fe0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 35 30 31 5d  nts:.** [H12501]
15ff0 20 5b 48 31 32 35 30 32 5d 20 5b 48 31 32 35 30   [H12502] [H1250
16000 33 5d 20 5b 48 31 32 35 30 34 5d 20 5b 48 31 32  3] [H12504] [H12
16010 35 30 35 5d 20 5b 48 31 32 35 30 36 5d 20 5b 48  505] [H12506] [H
16020 31 32 35 30 37 5d 20 5b 48 31 32 35 31 30 5d 0a  12507] [H12510].
16030 2a 2a 20 5b 48 31 32 35 31 31 5d 20 5b 48 31 32  ** [H12511] [H12
16040 35 31 32 5d 20 5b 48 31 32 35 32 30 5d 20 5b 48  512] [H12520] [H
16050 31 32 35 32 31 5d 20 5b 48 31 32 35 32 32 5d 0a  12521] [H12522].
16060 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
16070 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
16080 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
16090 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
160a0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
160b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
160c0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
160d0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
160e0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
160f0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
16100 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
16110 64 65 73 20 7b 48 31 32 35 39 30 7d 20 3c 48 31  des {H12590} <H1
16120 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2500>.**.** The 
16130 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
16140 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
16150 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
16160 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
16170 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
16180 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
16190 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
161a0 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
161b0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
161c0 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
161d0 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
161e0 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
161f0 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
16200 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
16210 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
16220 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
16230 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
16240 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23  nformation..*/.#
16250 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
16260 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
16270 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
16280 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
16290 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
162a0 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
162b0 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
162c0 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
162d0 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
162e0 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
162f0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
16300 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b 48   Action Codes {H
16310 31 32 35 35 30 7d 20 3c 48 31 32 35 30 30 3e 0a  12550} <H12500>.
16320 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
16330 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
16340 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
16350 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
16360 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
16370 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
16380 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
16390 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
163a0 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
163b0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
163c0 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
163d0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
163e0 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
163f0 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
16400 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
16410 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
16420 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
16430 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
16440 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
16450 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
16460 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
16470 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
16480 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
16490 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
164a0 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
164b0 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
164c0 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
164d0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
164e0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
164f0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
16500 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
16510 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
16520 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
16530 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
16540 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
16550 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
16560 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
16570 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
16580 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
16590 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
165a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
165b0 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
165c0 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
165d0 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
165e0 20 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65    The 6th parame
165f0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
16600 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
16610 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
16620 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
16630 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
16640 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
16650 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
16660 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
16670 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
16680 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
16690 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
166a0 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
166b0 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ode..**.** Requi
166c0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
166d0 35 35 31 5d 20 5b 48 31 32 35 35 32 5d 20 5b 48  551] [H12552] [H
166e0 31 32 35 35 33 5d 20 5b 48 31 32 35 35 34 5d 0a  12553] [H12554].
166f0 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
16700 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16710 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
16720 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
16730 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
16740 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16750 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
16760 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
16770 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
16780 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
16790 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
167a0 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
167b0 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
167c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
167d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
167e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
167f0 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
16800 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
16810 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
16820 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
16830 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
16840 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
16850 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
16860 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
16870 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
16880 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
16890 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
168a0 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
168b0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
168c0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
168d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
168e0 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
168f0 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
16900 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
16910 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
16920 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
16930 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
16940 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
16950 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
16960 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
16970 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
16980 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
16990 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
169a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
169b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
169c0 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
169d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
169e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
169f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
16a00 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
16a10 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
16a20 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
16a30 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
16a40 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
16a50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
16a60 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
16a70 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
16a80 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
16a90 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
16aa0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16ab0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
16ac0 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
16ad0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
16ae0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
16af0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16b00 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
16b10 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
16b20 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
16b30 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
16b40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
16b50 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
16b60 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
16b70 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
16b80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
16b90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16ba0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
16bb0 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
16bc0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
16bd0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
16be0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16bf0 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
16c00 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
16c10 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
16c20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
16c30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16c40 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
16c50 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
16c60 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
16c70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
16c80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16c90 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
16ca0 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
16cb0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
16cc0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
16cd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
16ce0 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
16cf0 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
16d00 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
16d10 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
16d20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
16d30 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
16d40 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
16d50 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
16d60 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
16d70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
16d80 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
16d90 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
16da0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
16db0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
16dc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
16dd0 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
16de0 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
16df0 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
16e00 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
16e10 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
16e20 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
16e30 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
16e40 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
16e50 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
16e60 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
16e70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
16e80 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
16e90 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
16ea0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
16eb0 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
16ec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
16ed0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
16ee0 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
16ef0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
16f00 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
16f10 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
16f20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
16f30 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
16f40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
16f50 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
16f60 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
16f70 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
16f80 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
16f90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16fa0 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
16fb0 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
16fc0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
16fd0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
16fe0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16ff0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
17000 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
17010 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
17020 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
17030 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17040 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
17050 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
17060 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17070 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
17080 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17090 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
170a0 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
170b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
170c0 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
170d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
170e0 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
170f0 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
17100 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
17110 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
17120 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17130 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
17140 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
17150 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
17160 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17170 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
17180 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
17190 20 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34 30   {H12280} <S6040
171a0 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
171b0 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  AL.**.** These r
171c0 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
171d0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
171e0 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
171f0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
17200 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
17210 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
17220 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
17230 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  s..**.** The cal
17240 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
17250 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
17260 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
17270 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
17280 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
17290 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
172a0 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
172b0 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
172c0 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  )]..** The callb
172d0 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54  ack returns a UT
172e0 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
172f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
17300 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68  nt text.** as th
17310 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
17320 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
17330 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  ng.  Additional 
17340 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a  callbacks occur.
17350 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
17360 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
17370 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
17380 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
17390 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
173a0 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
173b0 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
173c0 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
173d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  er..**.** The ca
173e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
173f0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
17400 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
17410 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
17420 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
17430 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54  ent finishes.  T
17440 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
17450 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
17460 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
17470 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
17480 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
17490 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
174a0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
174b0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
174c0 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  k to run..**.** 
174d0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
174e0 20 5b 48 31 32 32 38 31 5d 20 5b 48 31 32 32 38   [H12281] [H1228
174f0 32 5d 20 5b 48 31 32 32 38 33 5d 20 5b 48 31 32  2] [H12283] [H12
17500 32 38 34 5d 20 5b 48 31 32 32 38 35 5d 20 5b 48  284] [H12285] [H
17510 31 32 32 38 37 5d 20 5b 48 31 32 32 38 38 5d 20  12287] [H12288] 
17520 5b 48 31 32 32 38 39 5d 0a 2a 2a 20 5b 48 31 32  [H12289].** [H12
17530 32 39 30 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  290].*/.SQLITE_E
17540 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
17550 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
17560 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
17570 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
17580 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
17590 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  *);.SQLITE_EXPER
175a0 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
175b0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
175c0 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
175d0 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
175e0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
175f0 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
17600 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
17610 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
17620 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 20  gress Callbacks 
17630 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 34 30 30  {H12910} <S60400
17640 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
17650 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20  tine configures 
17660 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
17670 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f  ion - the.** pro
17680 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d  gress callback -
17690 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
176a0 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
176b0 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e  ring long.** run
176c0 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73  ning calls to [s
176d0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
176e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
176f0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
17700 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20  _get_table()].  
17710 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
17720 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
17730 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
17740 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
17750 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
17760 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ry..**.** If the
17770 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
17780 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
17790 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
177a0 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
177b0 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
177c0 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
177d0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
177e0 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
177f0 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
17800 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
17810 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
17820 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  ss handler must 
17830 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
17840 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
17850 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
17860 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
17870 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
17880 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
17890 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
178a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
178b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
178c0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
178d0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
178e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
178f0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
17900 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
17910 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
17920 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
17930 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 31 31 5d  nts:.** [H12911]
17940 20 5b 48 31 32 39 31 32 5d 20 5b 48 31 32 39 31   [H12912] [H1291
17950 33 5d 20 5b 48 31 32 39 31 34 5d 20 5b 48 31 32  3] [H12914] [H12
17960 39 31 35 5d 20 5b 48 31 32 39 31 36 5d 20 5b 48  915] [H12916] [H
17970 31 32 39 31 37 5d 20 5b 48 31 32 39 31 38 5d 0a  12917] [H12918].
17980 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
17990 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
179a0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
179b0 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
179c0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
179d0 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
179e0 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
179f0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31  e Connection {H1
17a00 32 37 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a  2700} <S40200>.*
17a10 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
17a20 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
17a30 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
17a40 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67   whose name is g
17a50 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66  iven by the.** f
17a60 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
17a70 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  . The filename a
17a80 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
17a90 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
17aa0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
17ab0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
17ac0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
17ad0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
17ae0 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
17af0 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
17b00 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41 20 5b 64  3_open16(). A [d
17b10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17b20 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
17b30 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
17b40 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
17b50 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
17b60 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
17b70 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
17b80 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
17b90 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
17ba0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
17bb0 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
17bc0 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
17bd0 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
17be0 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
17bf0 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
17c00 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
17c10 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 49  e3].** object. I
17c20 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
17c30 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
17c40 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
17c50 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
17c60 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
17c70 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
17c80 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
17c90 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
17ca0 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
17cb0 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
17cc0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
17cd0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
17ce0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
17cf0 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
17d00 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
17d10 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
17d20 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  or..**.** The de
17d30 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
17d40 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
17d50 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
17d60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
17d70 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
17d80 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  en_v2() is calle
17d90 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20  d and.** UTF-16 
17da0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
17db0 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69  te order if sqli
17dc0 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20  te3_open16() is 
17dd0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
17de0 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
17df0 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
17e00 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
17e10 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
17e20 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
17e30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17e40 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
17e50 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
17e60 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
17e70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
17e80 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
17e90 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
17ea0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
17eb0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
17ec0 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
17ed0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
17ee0 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
17ef0 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
17f00 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
17f10 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
17f20 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
17f30 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
17f40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17f50 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70  on.  The flags p
17f60 61 72 61 6d 65 74 65 72 20 63 61 6e 20 74 61 6b  arameter can tak
17f70 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
17f80 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
17f90 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
17fa0 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
17fb0 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
17fc0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
17fd0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
17fe0 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
17ff0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
18000 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53  E],.** and/or [S
18010 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
18020 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73 3a 0a  TECACHE] flags:.
18030 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
18040 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
18050 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
18060 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
18070 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
18080 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
18090 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
180a0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
180b0 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
180c0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
180d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
180e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
180f0 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
18100 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
18110 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
18120 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
18130 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
18140 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
18150 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
18160 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
18170 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
18180 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
18190 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
181a0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
181b0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
181c0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
181d0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
181e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53  dd>.**.** <dt>[S
181f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
18200 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
18210 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
18220 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
18230 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
18240 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
18250 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
18260 63 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a  creates it if.**
18270 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
18280 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
18290 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
182a0 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
182b0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
182c0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
182d0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
182e0 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
182f0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
18300 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
18310 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
18320 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
18330 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
18340 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20   shown above or 
18350 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69  one of the combi
18360 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
18370 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20  ove combined.** 
18380 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
18390 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
183a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
183b0 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c  LMUTEX],.** [SQL
183c0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
183d0 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51  ACHE] and/or [SQ
183e0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
183f0 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a  CACHE] flags,.**
18400 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
18410 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
18420 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53  .**.** If the [S
18430 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
18440 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
18450 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
18460 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
18470 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
18480 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
18490 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
184a0 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
184b0 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
184c0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
184d0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
184e0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
184f0 20 20 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    If the.** [SQL
18500 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
18510 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
18520 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
18530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
18540 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
18550 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
18560 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
18570 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
18580 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
18590 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
185a0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
185b0 74 2d 74 69 6d 65 2e 0a 2a 2a 20 54 68 65 20 5b  t-time..** The [
185c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
185d0 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
185e0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
185f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
18600 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
18610 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
18620 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
18630 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
18640 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
18650 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
18660 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
18670 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
18680 63 61 63 68 65 28 29 5d 2e 20 20 54 68 65 0a 2a  cache()].  The.*
18690 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
186a0 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
186b0 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
186c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
186d0 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
186e0 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
186f0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
18700 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
18710 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  led..**.** If th
18720 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
18730 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
18740 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
18750 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
18760 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
18770 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
18780 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69  nection.  This i
18790 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
187a0 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
187b0 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
187c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
187d0 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
187e0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
187f0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
18800 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
18810 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
18820 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
18830 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
18840 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
18850 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
18860 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
18870 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
18880 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
18890 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
188a0 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
188b0 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
188c0 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
188d0 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
188e0 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
188f0 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
18900 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
18910 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
18920 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
18930 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
18940 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
18950 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
18960 65 64 2e 20 20 54 68 69 73 20 70 72 69 76 61 74  ed.  This privat
18970 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
18980 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
18990 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
189a0 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
189b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
189c0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
189d0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
189e0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
189f0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
18a00 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
18a10 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
18a20 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
18a30 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
18a40 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
18a50 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
18a60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18a70 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
18a80 20 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20    If the fourth 
18a90 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
18aa0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
18ab0 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
18ac0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
18ad0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
18ae0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
18af0 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
18b00 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
18b10 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
18b20 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
18b30 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
18b40 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
18b50 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
18b60 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
18b70 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
18b80 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
18b90 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
18ba0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
18bb0 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
18bc0 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
18bd0 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
18be0 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
18bf0 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
18c00 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
18c10 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
18c20 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 52 65  n_v2()..**.** Re
18c30 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
18c40 48 31 32 37 30 31 5d 20 5b 48 31 32 37 30 32 5d  H12701] [H12702]
18c50 20 5b 48 31 32 37 30 33 5d 20 5b 48 31 32 37 30   [H12703] [H1270
18c60 34 5d 20 5b 48 31 32 37 30 36 5d 20 5b 48 31 32  4] [H12706] [H12
18c70 37 30 37 5d 20 5b 48 31 32 37 30 39 5d 20 5b 48  707] [H12709] [H
18c80 31 32 37 31 31 5d 0a 2a 2a 20 5b 48 31 32 37 31  12711].** [H1271
18c90 32 5d 20 5b 48 31 32 37 31 33 5d 20 5b 48 31 32  2] [H12713] [H12
18ca0 37 31 34 5d 20 5b 48 31 32 37 31 37 5d 20 5b 48  714] [H12717] [H
18cb0 31 32 37 31 39 5d 20 5b 48 31 32 37 32 31 5d 20  12719] [H12721] 
18cc0 5b 48 31 32 37 32 33 5d 0a 2a 2f 0a 69 6e 74 20  [H12723].*/.int 
18cd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
18ce0 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
18cf0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
18d00 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
18d10 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
18d20 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
18d30 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
18d40 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
18d50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
18d60 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
18d70 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
18d80 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
18d90 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
18da0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
18db0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
18dc0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
18dd0 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
18de0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
18df0 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
18e00 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
18e10 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
18e20 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
18e30 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
18e40 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
18e50 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
18e60 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
18e70 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
18e80 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
18e90 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
18ea0 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
18eb0 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
18ec0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18ed0 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
18ee0 64 20 4d 65 73 73 61 67 65 73 20 7b 48 31 32 38  d Messages {H128
18ef0 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a  00} <S60200>.**.
18f00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
18f10 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61  rrcode() interfa
18f20 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
18f30 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
18f40 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
18f50 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
18f60 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72  ] for the most r
18f70 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c  ecent failed sql
18f80 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a  ite3_* API call.
18f90 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
18fa0 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
18fb0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61  onnection]. If a
18fc0 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20   prior API call 
18fd0 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68  failed.** but th
18fe0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50  e most recent AP
18ff0 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64  I call succeeded
19000 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
19010 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  ue from.** sqlit
19020 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20  e3_errcode() is 
19030 75 6e 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20  undefined.  The 
19040 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
19050 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
19060 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
19070 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
19080 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
19090 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
190a0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
190b0 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
190c0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
190d0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
190e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
190f0 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
19100 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
19110 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
19120 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
19130 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
19140 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
19150 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
19160 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
19170 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  vely..** Memory 
19180 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
19190 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
191a0 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
191b0 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
191c0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
191d0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
191e0 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
191f0 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
19200 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
19210 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
19220 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
19230 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
19240 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
19250 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
19260 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
19270 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57  nctions..**.** W
19280 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
19290 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
192a0 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
192b0 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
192c0 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
192d0 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
192e0 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
192f0 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
19300 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
19310 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
19320 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
19330 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
19340 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
19350 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
19360 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
19370 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
19380 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
19390 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
193a0 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
193b0 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
193c0 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
193d0 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
193e0 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
193f0 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
19400 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
19410 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
19420 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
19430 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
19440 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
19450 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
19460 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
19470 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
19480 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
19490 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
194a0 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
194b0 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
194c0 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
194d0 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
194e0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
194f0 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
19500 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
19510 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
19520 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
19530 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
19540 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
19550 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
19560 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
19570 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
19580 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
19590 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
195a0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
195b0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 38 30 31 5d  nts:.** [H12801]
195c0 20 5b 48 31 32 38 30 32 5d 20 5b 48 31 32 38 30   [H12802] [H1280
195d0 33 5d 20 5b 48 31 32 38 30 37 5d 20 5b 48 31 32  3] [H12807] [H12
195e0 38 30 38 5d 20 5b 48 31 32 38 30 39 5d 0a 2a 2f  808] [H12809].*/
195f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
19600 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
19610 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
19620 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
19630 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
19640 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
19650 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
19660 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
19670 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
19680 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
19690 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
196a0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
196b0 74 20 7b 48 31 33 30 30 30 7d 20 3c 48 31 33 30  t {H13000} <H130
196c0 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  10>.** KEYWORDS:
196d0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
196e0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
196f0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
19700 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
19710 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
19720 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
19730 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
19740 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
19750 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
19760 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
19770 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
19780 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
19790 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
197a0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
197b0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
197c0 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
197d0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
197e0 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
197f0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
19800 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
19810 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
19820 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
19830 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
19840 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
19850 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
19860 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
19870 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
19880 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
19890 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
198a0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
198b0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
198c0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
198d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
198e0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
198f0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
19900 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
19910 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
19920 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
19930 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
19940 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
19950 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
19960 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
19970 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
19980 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
19990 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
199a0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
199b0 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
199c0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
199d0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
199e0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
199f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
19a00 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
19a10 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
19a20 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
19a30 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
19a40 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48 31 32 37  ime Limits {H127
19a50 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a  60} <S20600>.**.
19a60 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
19a70 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
19a80 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
19a90 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
19aa0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
19ab0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
19ac0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
19ad0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
19ae0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
19af0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19b00 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
19b10 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
19b20 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
19b30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
19b40 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
19b50 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
19b60 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
19b70 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
19b80 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
19b90 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
19ba0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
19bb0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
19bc0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
19bd0 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e  struct.  The fun
19be0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
19bf0 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a  e old limit..**.
19c00 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69  ** If the new li
19c10 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
19c20 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
19c30 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
19c40 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d  ..** For the lim
19c50 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53  it category of S
19c60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20  QLITE_LIMIT_XYZ 
19c70 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b  there is a .** [
19c80 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70  limits | hard up
19c90 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65  per bound].** se
19ca0 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74  t by a compile-t
19cb0 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73 73  ime C preprocess
19cc0 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a  or macro named .
19cd0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
19ce0 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a  ITE_MAX_XYZ]..**
19cf0 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
19d00 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
19d10 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
19d20 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20  ".).** Attempts 
19d30 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
19d40 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
19d50 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
19d60 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
19d70 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
19d80 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74  hard upper limit
19d90 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65  ..**.** Run time
19da0 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
19db0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
19dc0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
19dd0 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
19de0 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
19df0 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
19e00 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
19e10 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
19e20 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
19e30 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
19e40 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
19e50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
19e60 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
19e70 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
19e80 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
19e90 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
19ea0 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
19eb0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
19ec0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
19ed0 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
19ee0 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
19ef0 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
19f00 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
19f10 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
19f20 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
19f30 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
19f40 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
19f50 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
19f60 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
19f70 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
19f80 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
19f90 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
19fa0 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
19fb0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
19fc0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
19fd0 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
19fe0 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
19ff0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1a000 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
1a010 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
1a020 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
1a030 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
1a040 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
1a050 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
1a060 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
1a070 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
1a080 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
1a090 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
1a0a0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
1a0b0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
1a0c0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
1a0d0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
1a0e0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
1a0f0 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  s..**.** Require
1a100 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 36  ments:.** [H1276
1a110 32 5d 20 5b 48 31 32 37 36 36 5d 20 5b 48 31 32  2] [H12766] [H12
1a120 37 36 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  769].*/.int sqli
1a130 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
1a140 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
1a150 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
1a160 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
1a170 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
1a180 69 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48 31  ies {H12790} <H1
1a190 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  2760>.** KEYWORD
1a1a0 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
1a1b0 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  ry} {limit categ
1a1c0 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
1a1d0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
1a1e0 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
1a1f0 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
1a200 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
1a210 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
1a220 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
1a230 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
1a240 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
1a250 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
1a260 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
1a270 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
1a280 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
1a290 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
1a2a0 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
1a2b0 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
1a2c0 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
1a2d0 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
1a2e0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
1a2f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1a300 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
1a310 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
1a320 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64   or table row.<d
1a330 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1a340 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1a350 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1a360 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
1a370 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
1a380 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a  atement.</dd>.**
1a390 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1a3a0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
1a3b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1a3c0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
1a3d0 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
1a3e0 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
1a3f0 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
1a400 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
1a410 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
1a420 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1a430 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
1a440 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
1a450 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
1a460 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  clause.</dd>.**.
1a470 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1a480 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
1a490 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1a4a0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
1a4b0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
1a4c0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
1a4d0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1a4e0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
1a4f0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
1a500 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1a510 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1a520 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
1a530 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
1a540 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ment.</dd>.**.**
1a550 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1a560 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
1a570 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1a580 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
1a590 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
1a5a0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
1a5b0 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
1a5c0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
1a5d0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  L statement.</dd
1a5e0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1a5f0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
1a600 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
1a610 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1a620 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
1a630 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
1a640 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1a650 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
1a660 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
1a670 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1a680 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
1a690 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
1a6a0 61 73 65 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ases].</dd>.**.*
1a6b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1a6c0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
1a6d0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
1a6e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
1a6f0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
1a700 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
1a710 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
1a720 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
1a730 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  rs.</dd>.**.** <
1a740 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1a750 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
1a760 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1a770 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1a780 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61  f variables in a
1a790 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1a7a0 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62  that can.** be b
1a7b0 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ound.</dd>.**.**
1a7c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1a7d0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
1a7e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1a7f0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
1a800 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
1a810 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 0a 2a 2a  riggers.</dd>.**
1a820 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
1a830 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
1a840 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
1a850 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
1a860 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1a870 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
1a880 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
1a890 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1a8a0 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
1a8b0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
1a8c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1a8d0 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
1a8e0 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
1a8f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1a900 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
1a910 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
1a920 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1a930 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
1a940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
1a950 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1a960 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
1a970 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
1a980 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a990 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
1a9a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1a9b0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
1a9c0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
1a9d0 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
1a9e0 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
1a9f0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
1aa00 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
1aa10 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
1aa20 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
1aa30 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
1aa40 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    10../*.** CAPI
1aa50 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
1aa60 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
1aa70 20 7b 48 31 33 30 31 30 7d 20 3c 53 31 30 30 30   {H13010} <S1000
1aa80 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
1aa90 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  {SQL statement c
1aaa0 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54  ompiler}.**.** T
1aab0 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c  o execute an SQL
1aac0 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20   query, it must 
1aad0 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
1aae0 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
1aaf0 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
1ab00 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
1ab10 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
1ab20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
1ab30 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20  ent, "db", is a 
1ab40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ab50 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66  tion] obtained f
1ab60 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73  rom a.** prior s
1ab70 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1ab80 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
1ab90 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1aba0 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  n_v2()] or.** [s
1abb0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1abc0 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
1abd0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
1abe0 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c  not have been cl
1abf0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
1ac00 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
1ac10 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
1ac20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
1ac30 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
1ac40 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
1ac50 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
1ac60 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
1ac70 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
1ac80 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
1ac90 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
1aca0 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
1acb0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1acc0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1acd0 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
1ace0 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
1acf0 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
1ad00 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74  gument is less t
1ad10 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a  han zero, then z
1ad20 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
1ad30 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
1ad40 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1ad50 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
1ad60 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
1ad70 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
1ad80 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
1ad90 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
1ada0 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65  Sql.  When nByte
1adb0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
1adc0 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
1add0 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
1ade0 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
1adf0 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
1ae00 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
1ae10 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
1ae20 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
1ae30 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
1ae40 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
1ae50 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
1ae60 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
1ae70 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
1ae80 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
1ae90 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
1aea0 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
1aeb0 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
1aec0 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
1aed0 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
1aee0 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
1aef0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1af00 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
1af10 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
1af20 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
1af30 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
1af40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 70 7a 54 61 69  ..**.** If pzTai
1af50 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
1af60 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
1af70 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
1af80 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
1af90 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
1afa0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
1afb0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
1afc0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
1afd0 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
1afe0 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
1aff0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
1b000 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
1b010 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
1b020 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
1b030 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
1b040 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
1b050 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
1b060 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
1b070 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1b080 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
1b090 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1b0a0 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 49 66 20  e3_step()].  If 
1b0b0 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
1b0c0 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  r, *ppStmt is se
1b0d0 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49  t.** to NULL.  I
1b0e0 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
1b0f0 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
1b100 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
1b110 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
1b120 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
1b130 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
1b140 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
1b150 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
1b160 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
1b170 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
1b180 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
1b190 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
1b1a0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
1b1b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
1b1c0 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
1b1d0 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
1b1e0 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
1b1f0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  e NULL..**.** On
1b200 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
1b210 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
1b220 64 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  d, otherwise an 
1b230 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1b240 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1b250 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1b260 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
1b270 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1b280 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
1b290 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
1b2a0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
1b2b0 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
1b2c0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
1b2d0 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
1b2e0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1b2f0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
1b300 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
1b310 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49  iscouraged..** I
1b320 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
1b330 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
1b340 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
1b350 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
1b360 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
1b370 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
1b380 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
1b390 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
1b3a0 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
1b3b0 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
1b3c0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
1b3d0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
1b3e0 76 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79  ve a differently
1b3f0 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
1b400 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1b410 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  i>.** If the dat
1b420 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
1b430 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
1b440 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
1b450 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
1b460 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
1b470 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
1b480 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
1b490 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1b4a0 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
1b4b0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
1b4c0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
1b4d0 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65 6d  n.  If the schem
1b4e0 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e  a has changed in
1b4f0 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d  .** a way that m
1b500 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d 65  akes the stateme
1b510 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c  nt no longer val
1b520 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  id, [sqlite3_ste
1b530 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a  p()] will still.
1b540 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
1b550 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20  E_SCHEMA].  But 
1b560 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63  unlike the legac
1b570 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c  y behavior, [SQL
1b580 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a  ITE_SCHEMA] is.*
1b590 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72  * now a fatal er
1b5a0 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73  ror.  Calling [s
1b5b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1b5c0 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20  2()] again will 
1b5d0 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20  not make the.** 
1b5e0 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20  error go away.  
1b5f0 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74  Note: use [sqlit
1b600 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20  e3_errmsg()] to 
1b610 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a  find the text.**
1b620 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 20   of the parsing 
1b630 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c  error that resul
1b640 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  ts in an [SQLITE
1b650 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e  _SCHEMA] return.
1b660 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
1b670 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20  <li>.** When an 
1b680 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
1b690 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1b6a0 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
1b6b0 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
1b6c0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
1b6d0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
1b6e0 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54 68 65 20  or codes].  The 
1b6f0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
1b700 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
1b710 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
1b720 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
1b730 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
1b740 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
1b750 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 77  ode.** and you w
1b760 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
1b770 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
1b780 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
1b790 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  t()] in order.**
1b7a0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
1b7b0 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
1b7c0 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
1b7d0 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
1b7e0 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
1b7f0 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
1b800 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
1b810 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1b820 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
1b830 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
1b840 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  li>.** ^If the v
1b850 61 6c 75 65 20 6f 66 20 61 20 5b 70 61 72 61 6d  alue of a [param
1b860 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
1b870 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 57 48  meter] in the WH
1b880 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
1b890 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 71  .** change the q
1b8a0 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20  uery plan for a 
1b8b0 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 6e 20  statement, then 
1b8c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6d 61  the statement ma
1b8d0 79 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  y be.** automati
1b8e0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
1b8f0 20 28 61 73 20 69 66 20 74 68 65 72 65 20 68 61   (as if there ha
1b900 64 20 62 65 65 6e 20 61 20 73 63 68 65 6d 61 20  d been a schema 
1b910 63 68 61 6e 67 65 29 20 6f 6e 20 74 68 65 20 66  change) on the f
1b920 69 72 73 74 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  irst .** [sqlite
1b930 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
1b940 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
1b950 6e 67 65 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b  nge to the .** [
1b960 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1b970 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
1b980 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 5d   the [parameter]
1b990 2e 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  . .** </li>.** <
1b9a0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  /ol>.**.** Requi
1b9b0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1b9c0 30 31 31 5d 20 5b 48 31 33 30 31 32 5d 20 5b 48  011] [H13012] [H
1b9d0 31 33 30 31 33 5d 20 5b 48 31 33 30 31 34 5d 20  13013] [H13014] 
1b9e0 5b 48 31 33 30 31 35 5d 20 5b 48 31 33 30 31 36  [H13015] [H13016
1b9f0 5d 20 5b 48 31 33 30 31 39 5d 20 5b 48 31 33 30  ] [H13019] [H130
1ba00 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71  21].**.*/.int sq
1ba10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
1ba20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1ba30 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1ba40 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1ba50 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1ba60 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1ba70 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
1ba80 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1ba90 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1baa0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1bab0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1bac0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1bad0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1bae0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1baf0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1bb00 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1bb10 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1bb20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1bb30 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1bb40 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1bb50 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1bb60 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
1bb70 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1bb80 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1bb90 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1bba0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
1bbb0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1bbc0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
1bbd0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1bbe0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1bbf0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1bc00 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1bc10 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1bc20 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1bc30 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1bc40 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1bc50 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
1bc60 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1bc70 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1bc80 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1bc90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1bca0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
1bcb0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1bcc0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1bcd0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1bce0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
1bcf0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1bd00 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
1bd10 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1bd20 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1bd30 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1bd40 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1bd50 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1bd60 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1bd70 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1bd80 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1bd90 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
1bda0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1bdb0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1bdc0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1bdd0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
1bde0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1bdf0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
1be00 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1be10 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1be20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1be30 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1be40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1be50 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1be60 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1be70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1be80 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1be90 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1bea0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1beb0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1bec0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1bed0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1bee0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1bef0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1bf00 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1bf10 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1bf20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1bf30 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
1bf40 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31 33  atement SQL {H13
1bf50 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a 2a  100} <H13000>.**
1bf60 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1bf70 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
1bf80 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
1bf90 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
1bfa0 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
1bfb0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
1bfc0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
1bfd0 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
1bfe0 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
1bff0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
1c000 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
1c010 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1c020 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
1c030 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
1c040 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1c050 0a 2a 2a 20 5b 48 31 33 31 30 31 5d 20 5b 48 31  .** [H13101] [H1
1c060 33 31 30 32 5d 20 5b 48 31 33 31 30 33 5d 0a 2a  3102] [H13103].*
1c070 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1c080 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
1c090 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
1c0a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c0b0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
1c0c0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20  ed Value Object 
1c0d0 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32 30 30  {H15000} <S20200
1c0e0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
1c0f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1c100 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
1c110 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1c120 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
1c130 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
1c140 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1c150 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
1c160 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
1c170 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
1c180 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1c190 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
1c1a0 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
1c1b0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
1c1c0 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65  it stores. Value
1c1d0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
1c1e0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1c1f0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
1c200 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
1c210 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
1c220 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
1c230 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
1c240 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1c250 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
1c260 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
1c270 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
1c280 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
1c290 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
1c2a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1c2b0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
1c2c0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
1c2d0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
1c2e0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
1c2f0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
1c300 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
1c310 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
1c320 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
1c330 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
1c340 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
1c350 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
1c360 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
1c370 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1c380 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
1c390 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
1c3a0 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
1c3b0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
1c3c0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
1c3d0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
1c3e0 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65   A internal mute
1c3f0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
1c400 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1c410 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1c420 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
1c430 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
1c440 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1c450 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1c460 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
1c470 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
1c480 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
1c490 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
1c4a0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
1c4b0 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
1c4c0 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
1c4d0 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
1c4e0 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
1c4f0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
1c500 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
1c510 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
1c520 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
1c530 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
1c540 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
1c550 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
1c560 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
1c570 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
1c580 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
1c590 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1c5a0 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
1c5b0 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
1c5c0 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
1c5d0 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
1c5e0 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
1c5f0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
1c600 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
1c610 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
1c620 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
1c630 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
1c640 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72  tween between pr
1c650 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1c660 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1c670 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1c680 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
1c690 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
1c6a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1c6b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1c6c0 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
1c6d0 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
1c6e0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
1c6f0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
1c700 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1c710 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
1c720 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
1c730 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1c740 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
1c750 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
1c760 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
1c770 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
1c780 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
1c790 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1c7a0 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
1c7b0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
1c7c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
1c7d0 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
1c7e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
1c7f0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
1c800 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
1c810 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
1c820 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
1c830 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
1c840 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
1c850 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1c860 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
1c870 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
1c880 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
1c890 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c8a0 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
1c8b0 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48  ontext Object {H
1c8c0 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a  16001} <S20200>.
1c8d0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
1c8e0 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
1c8f0 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
1c900 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
1c910 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
1c920 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
1c930 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
1c940 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1c950 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
1c960 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
1c970 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
1c980 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1c990 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
1c9a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
1c9b0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1c9c0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
1c9d0 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
1c9e0 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
1c9f0 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
1ca00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
1ca10 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
1ca20 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
1ca30 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
1ca40 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
1ca50 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
1ca60 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1ca70 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
1ca80 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
1ca90 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
1caa0 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
1cab0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
1cac0 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
1cad0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
1cae0 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
1caf0 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
1cb00 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
1cb10 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
1cb20 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 31  d Statements {H1
1cb30 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3500} <S70300>.*
1cb40 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
1cb50 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
1cb60 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
1cb70 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
1cb80 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
1cb90 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
1cba0 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
1cbb0 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
1cbc0 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  nding}.**.** In 
1cbd0 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20  the SQL strings 
1cbe0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1cbf0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1cc00 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
1cc10 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
1cc20 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
1cc30 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
1cc40 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
1cc50 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
1cc60 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
1cc70 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
1cc80 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
1cc90 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
1cca0 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
1ccb0 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
1ccc0 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
1ccd0 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
1cce0 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
1ccf0 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
1cd00 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
1cd10 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
1cd20 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
1cd30 65 72 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20  er.  The values 
1cd40 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
1cd50 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
1cd60 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
1cd70 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
1cd80 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
1cd90 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
1cda0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
1cdb0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1cdc0 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
1cdd0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
1cde0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1cdf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1ce00 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
1ce10 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
1ce20 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1ce30 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
1ce40 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
1ce50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ce60 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
1ce70 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  iants..**.** The
1ce80 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1ce90 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
1cea0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
1ceb0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
1cec0 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51   The leftmost SQ
1ced0 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
1cee0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
1cef0 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
1cf00 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
1cf10 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
1cf20 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
1cf30 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
1cf40 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
1cf50 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
1cf60 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
1cf70 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
1cf80 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20  * The index for 
1cf90 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
1cfa0 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
1cfb0 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
1cfc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1cfd0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
1cfe0 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
1cff0 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f   The index.** fo
1d000 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
1d010 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
1d020 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20   of NNN..** The 
1d030 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
1d040 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
1d050 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
1d060 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
1d070 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
1d080 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
1d090 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
1d0a0 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  : 999)..**.** Th
1d0b0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1d0c0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
1d0d0 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
1d0e0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ameter..**.** In
1d0f0 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
1d100 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
1d110 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
1d120 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
1d130 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1d140 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
1d150 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
1d160 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
1d170 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
1d180 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
1d190 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
1d1a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1d1b0 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68  acters..** If th
1d1c0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1d1d0 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
1d1e0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
1d1f0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
1d200 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1d210 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
1d220 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
1d230 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  or..**.** The fi
1d240 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
1d250 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1d260 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
1d270 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
1d280 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1d290 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
1d2a0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
1d2b0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
1d2c0 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
1d2d0 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
1d2e0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
1d2f0 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68 20  t. If the fifth 
1d300 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
1d310 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
1d320 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
1d330 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
1d340 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
1d350 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
1d360 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
1d370 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
1d380 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
1d390 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66   be freed..** If
1d3a0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
1d3b0 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
1d3c0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
1d3d0 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
1d3e0 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
1d3f0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
1d400 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
1d410 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
1d420 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
1d430 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
1d440 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  returns..**.** T
1d450 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1d460 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
1d470 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
1d480 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
1d490 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
1d4a0 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65  th zeroes.  A ze
1d4b0 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
1d4c0 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
1d4d0 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
1d4e0 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
1d4f0 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
1d500 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
1d510 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
1d520 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
1d530 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
1d540 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
1d550 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
1d560 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
1d570 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
1d580 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
1d590 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
1d5a0 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
1d5b0 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69  nes..** A negati
1d5c0 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
1d5d0 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
1d5e0 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
1d5f0 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54  th BLOB..**.** T
1d600 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1d610 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  *() routines mus
1d620 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65  t be called afte
1d630 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
1d640 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64  epare_v2()] (and
1d650 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f   its variants) o
1d660 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
1d670 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72  ()] and.** befor
1d680 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1d690 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20  )]..** Bindings 
1d6a0 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
1d6b0 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
1d6c0 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
1d6d0 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72  ..** Unbound par
1d6e0 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
1d6f0 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
1d700 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1d710 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
1d720 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
1d730 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20  ess or an error 
1d740 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68  code if.** anyth
1d750 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20  ing goes wrong. 
1d760 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20   [SQLITE_RANGE] 
1d770 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
1d780 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
1d790 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
1d7a0 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f  range.  [SQLITE_
1d7b0 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
1d7c0 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
1d7d0 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45  ails..** [SQLITE
1d7e0 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62  _MISUSE] might b
1d7f0 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
1d800 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1d810 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20   called on a.** 
1d820 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
1d830 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e  that is the wron
1d840 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68  g state or which
1d850 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65   has already bee
1d860 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20  n finalized..** 
1d870 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73  Detection of mis
1d880 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c  use is unreliabl
1d890 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  e.  Applications
1d8a0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65   should not depe
1d8b0 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f  nd.** on SQLITE_
1d8c0 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20  MISUSE returns. 
1d8d0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69   SQLITE_MISUSE i
1d8e0 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e  s intended to in
1d8f0 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f  dicate a.** a lo
1d900 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65  gic error in the
1d910 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46   application.  F
1d920 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1d930 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
1d940 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74  * panic rather t
1d950 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54  han return SQLIT
1d960 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20  E_MISUSE..**.** 
1d970 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1d980 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1d990 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
1d9a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1d9b0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
1d9c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
1d9d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1d9e0 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  x()]..**.** Requ
1d9f0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1da00 33 35 30 36 5d 20 5b 48 31 33 35 30 39 5d 20 5b  3506] [H13509] [
1da10 48 31 33 35 31 32 5d 20 5b 48 31 33 35 31 35 5d  H13512] [H13515]
1da20 20 5b 48 31 33 35 31 38 5d 20 5b 48 31 33 35 32   [H13518] [H1352
1da30 31 5d 20 5b 48 31 33 35 32 34 5d 20 5b 48 31 33  1] [H13524] [H13
1da40 35 32 37 5d 0a 2a 2a 20 5b 48 31 33 35 33 30 5d  527].** [H13530]
1da50 20 5b 48 31 33 35 33 33 5d 20 5b 48 31 33 35 33   [H13533] [H1353
1da60 36 5d 20 5b 48 31 33 35 33 39 5d 20 5b 48 31 33  6] [H13539] [H13
1da70 35 34 32 5d 20 5b 48 31 33 35 34 35 5d 20 5b 48  542] [H13545] [H
1da80 31 33 35 34 38 5d 20 5b 48 31 33 35 35 31 5d 0a  13548] [H13551].
1da90 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  **.*/.int sqlite
1daa0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
1dab0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1dac0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1dad0 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
1dae0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
1daf0 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
1db00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1db10 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71   double);.int sq
1db20 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
1db30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1db40 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  t, int);.int sql
1db50 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
1db60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1db70 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
1db80 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  4);.int sqlite3_
1db90 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
1dba0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69  3_stmt*, int);.i
1dbb0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1dbc0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
1dbd0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
1dbe0 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  har*, int n, voi
1dbf0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
1dc00 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
1dc10 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
1dc20 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
1dc30 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
1dc40 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
1dc50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
1dc60 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
1dc70 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
1dc80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
1dc90 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1dca0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
1dcb0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
1dcc0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
1dcd0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
1dce0 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b  SQL Parameters {
1dcf0 48 31 33 36 30 30 7d 20 3c 53 37 30 33 30 30 3e  H13600} <S70300>
1dd00 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1dd10 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
1dd20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
1dd30 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
1dd40 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
1dd50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1dd60 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
1dd70 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
1dd80 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
1dd90 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
1dda0 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
1ddb0 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
1ddc0 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
1ddd0 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
1dde0 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
1ddf0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
1de00 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
1de10 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
1de20 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
1de30 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
1de40 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
1de50 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
1de60 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
1de70 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
1de80 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
1de90 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
1dea0 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
1deb0 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
1dec0 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
1ded0 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
1dee0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
1def0 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  NN are used,.** 
1df00 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
1df10 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a  s in the list..*
1df20 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1df30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1df40 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1df50 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1df60 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1df70 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
1df80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1df90 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1dfa0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1dfb0 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 30 31 5d 0a  ts:.** [H13601].
1dfc0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1dfd0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
1dfe0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
1dff0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1e000 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
1e010 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b 48  ost Parameter {H
1e020 31 33 36 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13620} <S70300>.
1e030 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
1e040 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
1e050 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65  nter to the name
1e060 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20   of the n-th.** 
1e070 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
1e080 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
1e090 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51  tatement]..** SQ
1e0a0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
1e0b0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
1e0c0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
1e0d0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
1e0e0 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
1e0f0 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
1e100 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
1e110 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
1e120 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
1e130 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
1e140 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
1e150 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
1e160 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
1e170 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
1e180 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
1e190 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73  e..** Parameters
1e1a0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
1e1b0 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
1e1c0 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
1e1d0 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
1e1e0 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72   are also referr
1e1f0 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d  ed to as "anonym
1e200 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
1e210 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
1e220 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
1e230 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
1e240 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
1e250 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69  If the value n i
1e260 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
1e270 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61  r if the n-th pa
1e280 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
1e290 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
1e2a0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
1e2b0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
1e2c0 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
1e2d0 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
1e2e0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
1e2f0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
1e300 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
1e310 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
1e320 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
1e330 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
1e340 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1e350 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
1e360 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1e370 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1e380 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
1e390 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
1e3a0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1e3b0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
1e3c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1e3d0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1e3e0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1e3f0 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 32 31 5d 0a  ts:.** [H13621].
1e400 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1e410 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1e420 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
1e430 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
1e440 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e450 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
1e460 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
1e470 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d  en Name {H13640}
1e480 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70300>.**.** 
1e490 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
1e4a0 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
1e4b0 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
1e4c0 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64  ame.  The.** ind
1e4d0 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
1e4e0 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
1e4f0 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
1e500 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
1e510 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1e520 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
1e530 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a  ind()].  A zero.
1e540 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
1e550 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
1e560 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
1e570 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 65 72  .  The parameter
1e580 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
1e590 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
1e5a0 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
1e5b0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
1e5c0 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
1e5d0 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
1e5e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
1e5f0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
1e600 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1e610 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1e620 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
1e630 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1e640 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1e650 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
1e660 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1e670 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
1e680 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
1e690 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 34 31  ents:.** [H13641
1e6a0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1e6b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1e6c0 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
1e6d0 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
1e6e0 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
1e6f0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
1e700 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
1e710 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
1e720 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53  ment {H13660} <S
1e730 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e  70300>.**.** Con
1e740 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
1e750 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
1e760 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1e770 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
1e780 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
1e790 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
1e7a0 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
1e7b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e7c0 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f  ..** Use this ro
1e7d0 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
1e7e0 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
1e7f0 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  rs to NULL..**.*
1e800 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
1e810 2a 2a 20 5b 48 31 33 36 36 31 5d 0a 2a 2f 0a 69  ** [H13661].*/.i
1e820 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
1e830 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
1e840 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
1e850 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
1e860 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
1e870 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31  A Result Set {H1
1e880 33 37 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3710} <S10700>.*
1e890 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
1e8a0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1e8b0 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
1e8c0 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
1e8d0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
1e8e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69   statement]. Thi
1e8f0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
1e900 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20  s 0 if pStmt is 
1e910 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  an SQL.** statem
1e920 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
1e930 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
1e940 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
1e950 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52  PDATE])..**.** R
1e960 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1e970 5b 48 31 33 37 31 31 5d 0a 2a 2f 0a 69 6e 74 20  [H13711].*/.int 
1e980 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
1e990 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
1e9a0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
1e9b0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
1e9c0 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
1e9d0 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 32 30  sult Set {H13720
1e9e0 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
1e9f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1ea00 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
1ea10 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
1ea20 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
1ea30 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
1ea40 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
1ea50 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  T] statement.  T
1ea60 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
1ea70 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
1ea80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
1ea90 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
1eaa0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1eab0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
1eac0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1ead0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
1eae0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1eaf0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1eb00 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
1eb10 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
1eb20 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
1eb30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1eb40 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
1eb50 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
1eb60 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68  T] statement. Th
1eb70 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1eb80 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
1eb90 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  umn number.  The
1eba0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
1ebb0 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
1ebc0 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
1ebd0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
1ebe0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
1ebf0 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
1ec00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
1ec10 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
1ec20 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
1ec30 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
1ec40 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
1ec50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
1ec60 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
1ec70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1ec80 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
1ec90 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49   column..**.** I
1eca0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
1ecb0 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
1ecc0 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
1ecd0 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
1ece0 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
1ecf0 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
1ed00 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
1ed10 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
1ed20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1ed30 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
1ed40 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
1ed50 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
1ed60 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
1ed70 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
1ed80 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
1ed90 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
1eda0 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
1edb0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
1edc0 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
1edd0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1ede0 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
1edf0 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
1ee00 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
1ee10 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
1ee20 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
1ee30 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
1ee40 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 32 31 5d  nts:.** [H13721]
1ee50 20 5b 48 31 33 37 32 33 5d 20 5b 48 31 33 37 32   [H13723] [H1372
1ee60 34 5d 20 5b 48 31 33 37 32 35 5d 20 5b 48 31 33  4] [H13725] [H13
1ee70 37 32 36 5d 20 5b 48 31 33 37 32 37 5d 0a 2a 2f  726] [H13727].*/
1ee80 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1ee90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1eea0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1eeb0 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
1eec0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
1eed0 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
1eee0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
1eef0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ef00 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
1ef10 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
1ef20 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30  lt {H13740} <S10
1ef30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  700>.**.** These
1ef40 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
1ef50 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
1ef60 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75  ermine what colu
1ef70 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61  mn of what.** ta
1ef80 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61 74  ble in which dat
1ef90 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f  abase a result o
1efa0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
1efb0 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f  tement comes fro
1efc0 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f  m..** The name o
1efd0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
1efe0 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
1eff0 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
1f000 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
1f010 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
1f020 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64   string.  The _d
1f030 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
1f040 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
1f050 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
1f060 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
1f070 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
1f080 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
1f090 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
1f0a0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
1f0b0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
1f0c0 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
1f0d0 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
1f0e0 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
1f0f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
1f100 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
1f110 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
1f120 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
1f130 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
1f140 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
1f150 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
1f160 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
1f170 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ding..**.** The 
1f180 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
1f190 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
1f1a0 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
1f1b0 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
1f1c0 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
1f1d0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  column..**.** Th
1f1e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1f1f0 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   to the followin
1f200 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72  g calls is a [pr
1f210 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f220 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  ]..** These func
1f230 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
1f240 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
1f250 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
1f260 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
1f270 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
1f280 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
1f290 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
1f2a0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ent..**.** If th
1f2b0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
1f2c0 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
1f2d0 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
1f2e0 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
1f2f0 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
1f300 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
1f310 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
1f320 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
1f330 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54  turn.** NULL.  T
1f340 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
1f350 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
1f360 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
1f370 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
1f380 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68  .** occurs.  Oth
1f390 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
1f3a0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
1f3b0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
1f3c0 61 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20  abase, table.** 
1f3d0 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  and column that 
1f3e0 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
1f3f0 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
1f400 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73  d from..**.** As
1f410 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
1f420 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
1f430 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74  se postfixed wit
1f440 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
1f450 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1f460 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68  strings, the oth
1f470 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
1f480 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d  urn UTF-8. {END}
1f490 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49  .**.** These API
1f4a0 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
1f4b0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
1f4c0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
1f4d0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
1f4e0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
1f4f0 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
1f500 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
1f510 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  ol defined..**.*
1f520 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66  * {A13751}.** If
1f530 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
1f540 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
1f550 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
1f560 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
1f570 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
1f580 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
1f590 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
1f5a0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
1f5b0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
1f5c0 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
1f5d0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1f5e0 3a 0a 2a 2a 20 5b 48 31 33 37 34 31 5d 20 5b 48  :.** [H13741] [H
1f5f0 31 33 37 34 32 5d 20 5b 48 31 33 37 34 33 5d 20  13742] [H13743] 
1f600 5b 48 31 33 37 34 34 5d 20 5b 48 31 33 37 34 35  [H13744] [H13745
1f610 5d 20 5b 48 31 33 37 34 36 5d 20 5b 48 31 33 37  ] [H13746] [H137
1f620 34 38 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  48].**.** If two
1f630 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
1f640 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
1f650 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
1f660 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1f670 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
1f680 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
1f690 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
1f6a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f6b0 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
1f6c0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
1f6d0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
1f6e0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
1f6f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63   undefined..*/.c
1f700 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1f710 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
1f720 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
1f730 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
1f740 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1f750 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
1f760 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
1f770 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
1f780 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
1f790 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
1f7a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1f7b0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
1f7c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1f7d0 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
1f7e0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
1f7f0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1f800 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
1f810 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
1f820 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
1f830 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1f840 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
1f850 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
1f860 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
1f870 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
1f880 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
1f890 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48   Query Result {H
1f8a0 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a  13760} <S10700>.
1f8b0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
1f8c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
1f8d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f8e0 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
1f8f0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
1f900 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1f910 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
1f920 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
1f930 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
1f940 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
1f950 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
1f960 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
1f970 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
1f980 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
1f990 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
1f9a0 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
1f9b0 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
1f9c0 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20  ed.  If the Nth 
1f9d0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
1f9e0 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
1f9f0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
1fa00 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
1fa10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
1fa20 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68   returned..** Th
1fa30 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
1fa40 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
1fa50 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d  8 encoded. {END}
1fa60 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
1fa70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
1fa80 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
1fa90 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
1faa0 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
1fab0 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
1fac0 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
1fad0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
1fae0 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
1faf0 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
1fb00 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
1fb10 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
1fb20 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
1fb30 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
1fb40 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
1fb50 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
1fb60 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
1fb70 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
1fb80 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
1fb90 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53   (i==0)..**.** S
1fba0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
1fbb0 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
1fbc0 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63  ng.  So just bec
1fbd0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
1fbe0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
1fbf0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
1fc00 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
1fc10 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
1fc20 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
1fc30 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
1fc40 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
1fc50 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
1fc60 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
1fc70 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
1fc80 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
1fc90 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70  not static.  Typ
1fca0 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
1fcb0 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
1fcc0 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
1fcd0 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
1fce0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
1fcf0 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
1fd00 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
1fd10 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 36 31 5d  nts:.** [H13761]
1fd20 20 5b 48 31 33 37 36 32 5d 20 5b 48 31 33 37 36   [H13762] [H1376
1fd30 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  3].*/.const char
1fd40 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1fd50 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
1fd60 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
1fd70 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
1fd80 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
1fd90 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
1fda0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
1fdb0 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
1fdc0 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
1fdd0 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30  nt {H13200} <S10
1fde0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  000>.**.** After
1fdf0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1fe00 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
1fe10 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
1fe20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
1fe30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1fe40 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
1fe50 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
1fe60 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
1fe70 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
1fe80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fe90 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1fea0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
1feb0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
1fec0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
1fed0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
1fee0 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
1fef0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
1ff00 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
1ff10 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
1ff20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
1ff30 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
1ff40 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
1ff50 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
1ff60 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
1ff70 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
1ff80 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
1ff90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ffa0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
1ffb0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1ffc0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
1ffd0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
1ffe0 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
1fff0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
20000 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
20010 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
20020 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
20030 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
20040 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
20050 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
20060 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
20070 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
20080 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
20090 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ported..**.** In
200a0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
200b0 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
200c0 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
200d0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
200e0 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
200f0 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
20100 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
20110 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
20120 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74  _MISUSE]..** Wit
20130 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
20140 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
20150 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
20160 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
20170 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
20180 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
20190 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
201a0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  *.** [SQLITE_BUS
201b0 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
201c0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
201d0 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
201e0 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
201f0 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
20200 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
20210 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74   job.  If the st
20220 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
20230 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
20240 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
20250 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
20260 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
20270 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
20280 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
20290 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
202a0 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
202b0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
202c0 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
202d0 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
202e0 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
202f0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
20300 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
20310 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
20320 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d   [SQLITE_DONE] m
20330 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
20340 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
20350 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
20360 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
20370 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
20380 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
20390 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
203a0 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
203b0 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
203c0 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
203d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
203e0 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
203f0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
20400 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
20410 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49  l state..**.** I
20420 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
20430 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
20440 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
20450 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
20460 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
20470 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
20480 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
20490 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
204a0 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
204b0 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
204c0 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
204d0 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
204e0 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
204f0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
20500 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
20510 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
20520 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
20530 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
20540 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  **.** [SQLITE_ER
20550 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
20560 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
20570 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
20580 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
20590 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
205a0 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
205b0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
205c0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
205d0 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
205e0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
205f0 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
20600 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
20610 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68  rmsg()]..** With
20620 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
20630 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
20640 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
20650 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
20660 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
20670 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
20680 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
20690 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
206a0 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
206b0 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
206c0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
206d0 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
206e0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
206f0 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20  ement].  In the 
20700 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
20710 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
20720 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
20730 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
20740 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
20750 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
20760 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
20770 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
20780 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
20790 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
207a0 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
207b0 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
207c0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
207d0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
207e0 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
207f0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
20800 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
20810 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
20820 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
20830 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
20840 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
20850 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
20860 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
20870 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
20880 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
20890 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
208a0 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
208b0 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
208c0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
208d0 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
208e0 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
208f0 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
20900 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
20910 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
20920 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
20930 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
20940 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
20950 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
20960 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
20970 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
20980 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
20990 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
209a0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
209b0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
209c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
209d0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
209e0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
209f0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
20a00 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
20a10 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
20a20 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
20a30 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
20a40 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
20a50 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
20a60 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
20a70 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
20a80 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
20a90 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
20aa0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
20ab0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
20ac0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
20ad0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
20ae0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20af0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
20b00 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
20b10 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
20b20 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
20b30 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
20b40 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
20b50 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
20b60 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
20b70 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
20b80 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
20b90 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
20ba0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
20bb0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
20bc0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
20bd0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
20be0 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  ended..**.** Req
20bf0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
20c00 31 33 32 30 32 5d 20 5b 48 31 35 33 30 34 5d 20  13202] [H15304] 
20c10 5b 48 31 35 33 30 36 5d 20 5b 48 31 35 33 30 38  [H15306] [H15308
20c20 5d 20 5b 48 31 35 33 31 30 5d 0a 2a 2f 0a 69 6e  ] [H15310].*/.in
20c30 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
20c40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
20c50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20c60 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
20c70 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
20c80 74 20 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 37  t {H13770} <S107
20c90 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  00>.**.** Return
20ca0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
20cb0 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75  values in the cu
20cc0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
20cd0 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a   result set..**.
20ce0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
20cf0 0a 2a 2a 20 5b 48 31 33 37 37 31 5d 20 5b 48 31  .** [H13771] [H1
20d00 33 37 37 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  3772].*/.int sql
20d10 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
20d20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
20d30 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
20d40 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
20d50 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48 31  al Datatypes {H1
20d60 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53  0265} <S10110><S
20d70 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  10120>.** KEYWOR
20d80 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
20d90 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45  **.** {H10266} E
20da0 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
20db0 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
20dc0 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
20dd0 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
20de0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
20df0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
20e00 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
20e10 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
20e20 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
20e30 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
20e40 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
20e50 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
20e60 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
20e70 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
20e80 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
20e90 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
20ea0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
20eb0 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
20ec0 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
20ed0 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
20ee0 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
20ef0 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
20f00 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
20f10 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
20f20 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
20f30 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
20f40 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
20f50 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
20f60 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
20f70 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
20f80 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
20f90 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
20fa0 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
20fb0 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
20fc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20fd0 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
20fe0 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
20ff0 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
21000 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
21010 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
21020 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
21030 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
21040 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
21050 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
21060 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21070 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
21080 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33 38  om A Query {H138
21090 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20  00} <S10700>.** 
210a0 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
210b0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
210c0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
210d0 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
210e0 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75  e "result set qu
210f0 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  ery" interface..
21100 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
21110 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
21120 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
21130 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
21140 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
21150 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
21160 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79  query.  In every
21170 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
21180 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
21190 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
211a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
211b0 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
211c0 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
211d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
211e0 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
211f0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
21200 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21210 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
21220 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
21230 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
21240 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
21250 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
21260 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
21270 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
21280 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54   be returned.  T
21290 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
212a0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
212b0 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
212c0 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ex 0..**.** If t
212d0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
212e0 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
212f0 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
21300 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
21310 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
21320 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
21330 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
21340 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
21350 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
21360 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
21370 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
21380 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
21390 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
213a0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
213b0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
213c0 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
213d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
213e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
213f0 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
21400 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
21410 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
21420 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
21430 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
21440 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
21450 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
21460 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
21470 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
21480 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
21490 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
214a0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
214b0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
214c0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
214d0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
214e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
214f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
21500 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
21510 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
21520 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
21530 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
21540 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
21550 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
21560 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
21570 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
21580 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
21590 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
215a0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
215b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
215c0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
215d0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
215e0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
215f0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
21600 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
21610 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72  t column.  The r
21620 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
21630 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
21640 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
21650 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
21660 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
21670 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
21680 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
21690 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
216a0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
216b0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
216c0 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
216d0 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
216e0 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
216f0 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
21700 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
21710 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
21720 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
21730 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
21740 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
21750 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
21760 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
21770 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
21780 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
21790 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
217a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
217b0 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
217c0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
217d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
217e0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
217f0 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
21800 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
21810 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
21820 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
21830 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
21840 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
21850 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
21860 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
21870 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
21880 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
21890 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
218a0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
218b0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
218c0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
218d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
218e0 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ytes..** If the 
218f0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
21900 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
21910 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
21920 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
21930 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
21940 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
21950 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
21960 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
21970 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
21980 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
21990 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
219a0 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   The value retur
219b0 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
219c0 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
219d0 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20  rminator at the 
219e0 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
219f0 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69  ring.  For clari
21a00 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65  ty: the value re
21a10 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75  turned is the nu
21a20 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
21a30 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
21a40 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
21a50 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
21a60 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75  .** Strings retu
21a70 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
21a80 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
21a90 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
21aa0 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
21ab0 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
21ac0 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
21ad0 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54  o terminated.  T
21ae0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
21af0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
21b00 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
21b10 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
21b20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74  BLOB is an arbit
21b30 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c  rary.** pointer,
21b40 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61   possibly even a
21b50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
21b60 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
21b70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
21b80 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
21b90 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  ilar to sqlite3_
21ba0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
21bb0 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65  * but leaves the
21bc0 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31   result in UTF-1
21bd0 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  6 in native byte
21be0 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f   order instead o
21bf0 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20  f UTF-8..** The 
21c00 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
21c10 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20  is not included 
21c20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a  in this count..*
21c30 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20  *.** The object 
21c40 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
21c50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
21c60 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
21c70 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
21c80 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
21c90 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
21ca0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
21cb0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
21cc0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
21cd0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
21ce0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
21cf0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
21d00 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
21d10 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
21d20 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
21d30 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
21d40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
21d50 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
21d60 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
21d70 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
21d80 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
21d90 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
21da0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
21db0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
21dc0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
21dd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
21de0 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
21df0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
21e00 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
21e10 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
21e20 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
21e30 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
21e40 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a  propriate.  For.
21e50 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
21e60 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
21e70 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
21e80 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
21e90 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
21ea0 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
21eb0 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
21ec0 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
21ed0 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
21ee0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
21ef0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
21f00 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
21f10 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
21f20 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
21f30 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
21f40 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
21f50 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
21f60 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
21f70 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
21f80 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
21f90 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
21fa0 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
21fb0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
21fc0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
21fd0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
21fe0 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
21ff0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
22000 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
22010 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
22020 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
22030 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
22040 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
22050 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
22060 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
22070 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
22080 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
22090 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
220a0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
220b0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
220c0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
220d0 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
220e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
220f0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
22100 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
22110 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
22120 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
22130 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
22140 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
22150 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
22160 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
22170 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
22180 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
22190 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
221a0 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
221b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
221c0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
221d0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
221e0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
221f0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
22200 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
22210 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
22220 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
22230 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
22240 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
22250 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
22260 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
22270 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
22280 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
22290 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
222a0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
222b0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
222c0 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
222d0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
222e0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
222f0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
22300 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
22310 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
22320 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
22330 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
22340 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
22350 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
22360 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
22370 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
22380 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
22390 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
223a0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
223b0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
223c0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ote>.**.** The t
223d0 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
223e0 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
223f0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
22400 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
22410 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
22420 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
22430 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
22440 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
22450 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
22460 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
22470 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
22480 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
22490 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
224a0 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
224b0 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
224c0 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
224d0 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
224e0 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
224f0 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
22500 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
22510 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
22520 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
22530 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
22540 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
22550 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
22560 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
22570 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
22580 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
22590 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
225a0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
225b0 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
225c0 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
225d0 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
225e0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
225f0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
22600 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
22610 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
22620 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
22630 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
22640 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
22650 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
22660 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
22670 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
22680 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
22690 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
226a0 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
226b0 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
226c0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
226d0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
226e0 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
226f0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
22700 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
22710 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
22720 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
22730 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
22740 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
22750 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
22760 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
22770 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
22780 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
22790 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
227a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
227b0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
227c0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
227d0 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
227e0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
227f0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
22800 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
22810 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
22820 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69  >.**.** Conversi
22830 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
22840 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
22850 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
22860 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
22870 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
22880 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
22890 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
228a0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
228b0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
228c0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
228d0 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73  r pointer points
228e0 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65   to will have be
228f0 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
22900 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
22910 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
22920 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
22930 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
22940 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
22950 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
22960 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
22970 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
22980 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
22990 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
229a0 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64  * The safest and
229b0 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65   easiest to reme
229c0 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74  mber policy is t
229d0 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
229e0 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
229f0 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
22a00 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
22a10 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
22a20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
22a30 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
22a40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
22a50 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
22a60 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
22a70 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
22a80 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
22a90 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
22aa0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
22ab0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
22ac0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
22ad0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
22ae0 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
22af0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
22b00 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
22b10 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
22b20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
22b30 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
22b40 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
22b50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
22b60 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
22b70 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
22b80 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
22b90 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
22ba0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
22bb0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
22bc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
22bd0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
22be0 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
22bf0 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
22c00 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
22c10 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
22c20 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
22c30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
22c40 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
22c50 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
22c60 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
22c70 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
22c80 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
22c90 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
22ca0 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
22cb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22cc0 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ytes()..**.** Th
22cd0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
22ce0 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
22cf0 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
22d00 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
22d10 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
22d20 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
22d30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
22d40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
22d50 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
22d60 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
22d70 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65   called.  The me
22d80 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
22d90 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
22da0 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
22db0 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
22dc0 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
22dd0 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
22de0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
22df0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
22e00 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
22e10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
22e20 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
22e30 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
22e40 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65  ]..**.** If a me
22e50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
22e60 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
22e70 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
22e80 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
22e90 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
22ea0 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
22eb0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
22ec0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
22ed0 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
22ee0 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
22ef0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
22f00 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
22f10 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
22f20 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
22f30 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
22f40 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
22f50 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
22f60 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52  _NOMEM]..**.** R
22f70 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
22f80 5b 48 31 33 38 30 33 5d 20 5b 48 31 33 38 30 36  [H13803] [H13806
22f90 5d 20 5b 48 31 33 38 30 39 5d 20 5b 48 31 33 38  ] [H13809] [H138
22fa0 31 32 5d 20 5b 48 31 33 38 31 35 5d 20 5b 48 31  12] [H13815] [H1
22fb0 33 38 31 38 5d 20 5b 48 31 33 38 32 31 5d 20 5b  3818] [H13821] [
22fc0 48 31 33 38 32 34 5d 0a 2a 2a 20 5b 48 31 33 38  H13824].** [H138
22fd0 32 37 5d 20 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a  27] [H13830].*/.
22fe0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
22ff0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
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 69 6e 74 20 73 71  nt iCol);.int sq
23020 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
23030 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
23040 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
23050 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23060 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
23070 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
23080 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
23090 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
230a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
230b0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
230c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
230d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
230e0 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
230f0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
23100 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
23110 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
23120 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  iCol);.const uns
23130 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
23140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
23150 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
23160 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
23170 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
23180 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
23190 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
231a0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
231b0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
231c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
231d0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
231e0 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
231f0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
23200 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
23210 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
23220 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
23230 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
23240 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33  ent Object {H133
23250 30 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33 30  00} <S70300><S30
23260 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  100>.**.** The s
23270 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
23280 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
23290 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
232a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
232b0 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ment]..** If the
232c0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65   statement was e
232d0 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66  xecuted successf
232e0 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63  ully or not exec
232f0 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65  uted at all, the
23300 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69  n.** SQLITE_OK i
23310 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20 65  s returned. If e
23320 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
23330 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64  statement failed
23340 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72   then an.** [err
23350 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  or code] or [ext
23360 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
23370 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
23380 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
23390 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
233a0 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
233b0 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
233c0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  n of the.** [pre
233d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
233e0 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61  .  If the virtua
233f0 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f  l machine has no
23400 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  t.** completed e
23410 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68  xecution when th
23420 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  is routine is ca
23430 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69  lled, that is li
23440 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69  ke.** encounteri
23450 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61  ng an error or a
23460 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  n [sqlite3_inter
23470 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74  rupt | interrupt
23480 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65  ]..** Incomplete
23490 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20   updates may be 
234a0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20  rolled back and 
234b0 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e  transactions can
234c0 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64  celed,.** depend
234d0 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75  ing on the circu
234e0 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68  mstances, and th
234f0 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  e.** [error code
23500 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20  ] returned will 
23510 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  be [SQLITE_ABORT
23520 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
23530 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 33 30  ments:.** [H1130
23540 32 5d 20 5b 48 31 31 33 30 34 5d 0a 2a 2f 0a 69  2] [H11304].*/.i
23550 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
23560 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
23570 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
23580 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
23590 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
235a0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31  ement Object {H1
235b0 33 33 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3330} <S70300>.*
235c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
235d0 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
235e0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
235f0 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
23600 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
23610 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
23620 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
23630 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
23640 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79  executed..** Any
23650 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
23660 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
23670 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
23680 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
23690 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
236a0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
236b0 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
236c0 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
236d0 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
236e0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
236f0 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
23700 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
23710 2a 2a 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20  ** {H11332} The 
23720 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
23730 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
23740 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
23750 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
23760 2a 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20  *          back 
23770 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
23780 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
23790 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20  .**.** {H11334} 
237a0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
237b0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
237c0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
237d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
237e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
237f0 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
23800 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
23810 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
23820 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
23830 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
23840 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
23850 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
23860 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20   on S,.**       
23870 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
23880 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
23890 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
238a0 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49  **.** {H11336} I
238b0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
238c0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
238d0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
238e0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
238f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23900 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
23910 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
23920 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
23930 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
23940 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
23950 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
23960 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33  e]..**.** {H1133
23970 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
23980 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
23990 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
239a0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
239b0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e  *          of an
239c0 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
239d0 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
239e0 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
239f0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
23a00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
23a10 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
23a20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
23a30 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
23a40 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
23a50 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31   Functions {H161
23a60 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20  00} <S20200>.** 
23a70 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
23a80 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
23a90 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
23aa0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
23ab0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
23ac0 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
23ad0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
23ae0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
23af0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
23b00 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ese two function
23b10 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
23b20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
23b30 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
23b40 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
23b50 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
23b60 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
23b70 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
23b80 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
23b90 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
23ba0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
23bb0 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
23bc0 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
23bd0 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a  ce between the.*
23be0 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68  * two is that th
23bf0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
23c00 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  er, the name of 
23c10 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e  the (scalar) fun
23c20 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
23c30 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65  egate, is encode
23c40 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73  d in UTF-8 for s
23c50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
23c60 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46  nction() and UTF
23c70 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  -16.** for sqlit
23c80 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
23c90 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  on16()..**.** Th
23ca0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
23cb0 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
23cc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
23cd0 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
23ce0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
23cf0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20  o be added.  If 
23d00 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d  a single program
23d10 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
23d20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
23d30 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72  connection inter
23d40 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20  nally, then SQL 
23d50 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
23d60 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75  e added individu
23d70 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20  ally to.** each 
23d80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23d90 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
23da0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
23db0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
23dc0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
23dd0 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
23de0 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
23df0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
23e00 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
23e10 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20  d to 255 bytes, 
23e20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20  exclusive of.** 
23e30 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
23e40 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  tor.  Note that 
23e50 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20  the name length 
23e60 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65  limit is in byte
23e70 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63  s, not.** charac
23e80 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d  ters.  Any attem
23e90 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
23ea0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
23eb0 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
23ec0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
23ed0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e  LITE_ERROR] bein
23ee0 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
23ef0 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61  * The third para
23f00 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
23f10 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
23f20 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
23f30 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
23f40 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
23f50 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20   takes. If this 
23f60 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c  parameter is -1,
23f70 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
23f80 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
23f90 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
23fa0 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
23fb0 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20  guments between 
23fc0 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a  0 and the limit.
23fd0 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74  ** set by [sqlit
23fe0 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
23ff0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
24000 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20  _ARG]).  If the 
24010 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
24020 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
24030 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
24040 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20  an 127 then the 
24050 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
24060 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
24070 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
24080 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
24090 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
240a0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
240b0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
240c0 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
240d0 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
240e0 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
240f0 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69    Any SQL functi
24100 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
24110 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65  n should be able
24120 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b   to work.** work
24130 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46   with UTF-8, UTF
24140 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36  -16le, or UTF-16
24150 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d  be.  But some im
24160 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
24170 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66  y be.** more eff
24180 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20  icient with one 
24190 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e  encoding than an
241a0 6f 74 68 65 72 2e 20 20 41 6e 20 61 70 70 6c 69  other.  An appli
241b0 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e  cation may.** in
241c0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
241d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
241e0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
241f0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
24200 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
24210 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
24220 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
24230 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
24240 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
24250 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69   When multiple i
24260 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
24270 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
24280 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
24290 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
242a0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
242b0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
242c0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
242d0 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
242e0 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
242f0 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
24300 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
24310 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
24320 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65  e what text.** e
24330 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
24340 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
24350 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
24360 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d   be [SQLITE_ANY]
24370 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
24380 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
24390 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
243a0 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
243b0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
243c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
243d0 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
243e0 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
243f0 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
24400 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  data()]..**.** T
24410 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68  he seventh, eigh
24420 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72  th and ninth par
24430 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
24440 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
24450 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
24460 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
24470 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
24480 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
24490 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
244a0 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61  aggregate. A sca
244b0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
244c0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
244d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
244e0 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
244f0 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20  back only, NULL 
24500 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20  pointers should 
24510 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
24520 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
24530 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
24540 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51   An aggregate SQ
24550 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
24560 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
24570 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
24580 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
24590 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20   NULL should be 
245a0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
245b0 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65  . To delete an e
245c0 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
245d0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
245e0 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
245f0 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
24600 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73  nction callbacks
24610 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65  ..**.** It is pe
24620 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
24630 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
24640 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
24650 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
24660 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
24670 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
24680 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
24690 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
246a0 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
246b0 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
246c0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
246d0 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  .  SQLite will u
246e0 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
246f0 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
24700 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
24710 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
24720 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
24730 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
24740 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70    A function imp
24750 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
24760 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a   a non-negative.
24770 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65  ** nArg paramete
24780 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61  r is a better ma
24790 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
247a0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
247b0 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67  on with.** a neg
247c0 61 74 69 76 65 20 6e 41 72 67 2e 20 20 41 20 66  ative nArg.  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 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
247f0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
24800 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
24810 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
24820 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
24830 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
24840 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
24850 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
24860 20 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e    .** A function
24870 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
24880 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
24890 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
248a0 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
248b0 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
248c0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
248d0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
248e0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
248f0 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
24900 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
24910 2a 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75  *.** Built-in fu
24920 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
24930 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
24940 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
24950 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
24960 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 70 70  ** The first app
24970 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
24980 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
24990 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72   given name over
249a0 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69  rides all.** bui
249b0 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
249c0 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  in the same [dat
249d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
249e0 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  ] with the same 
249f0 6e 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75  name..** Subsequ
24a00 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ent application-
24a10 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
24a20 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61  s of the same na
24a30 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65  me only override
24a40 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69   .** prior appli
24a50 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
24a60 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72  unctions that ar
24a70 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68  e an exact match
24a80 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62   for the.** numb
24a90 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
24aa0 20 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65   and preferred e
24ab0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41  ncoding..**.** A
24ac0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
24ad0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
24ae0 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
24af0 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
24b00 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
24b10 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
24b20 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
24b30 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
24b40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
24b50 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
24b60 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
24b70 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
24b80 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
24b90 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
24ba0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
24bb0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 31 30 33 5d  nts:.** [H16103]
24bc0 20 5b 48 31 36 31 30 36 5d 20 5b 48 31 36 31 30   [H16106] [H1610
24bd0 39 5d 20 5b 48 31 36 31 31 32 5d 20 5b 48 31 36  9] [H16112] [H16
24be0 31 31 38 5d 20 5b 48 31 36 31 32 31 5d 20 5b 48  118] [H16121] [H
24bf0 31 36 31 32 37 5d 0a 2a 2a 20 5b 48 31 36 31 33  16127].** [H1613
24c00 30 5d 20 5b 48 31 36 31 33 33 5d 20 5b 48 31 36  0] [H16133] [H16
24c10 31 33 36 5d 20 5b 48 31 36 31 33 39 5d 20 5b 48  136] [H16139] [H
24c20 31 36 31 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71  16142].*/.int sq
24c30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
24c40 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
24c50 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
24c60 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
24c70 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
24c80 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
24c90 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
24ca0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
24cb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
24cc0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
24cd0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
24ce0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
24cf0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
24d00 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
24d10 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
24d20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
24d30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
24d40 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
24d50 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
24d60 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
24d70 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
24d80 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
24d90 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
24da0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
24db0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
24dc0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
24dd0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
24de0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
24df0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
24e00 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
24e10 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
24e20 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
24e30 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  text*).);../*.**
24e40 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
24e50 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36  Encodings {H1026
24e60 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36  7} <S50200> <H16
24e70 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  100>.**.** These
24e80 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
24e90 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
24ea0 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
24eb0 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
24ec0 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
24ed0 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
24ee0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
24ef0 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
24f00 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
24f10 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
24f20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
24f30 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
24f40 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
24f50 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
24f60 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
24f70 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
24f80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24f90 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
24fa0 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
24fb0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
24fc0 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
24fd0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
24fe0 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
24ff0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
25000 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
25010 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25020 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
25030 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
25040 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
25050 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
25060 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
25070 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
25080 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
25090 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
250a0 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
250b0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
250c0 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
250d0 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
250e0 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
250f0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
25100 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
25110 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
25120 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
25130 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
25140 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
25150 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
25160 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
25170 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61   to tell you wha
25180 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
25190 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
251a0 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
251b0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
251c0 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
251d0 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
251e0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
251f0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
25200 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
25210 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
25220 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
25230 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
25240 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
25250 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
25260 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
25270 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
25280 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
25290 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
252a0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
252b0 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
252c0 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
252d0 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
252e0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
252f0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
25300 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
25310 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
25320 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71  64,int),void*,sq
25330 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
25340 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
25350 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
25360 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
25370 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48  ameter Values {H
25380 31 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  15100} <S20200>.
25390 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
253a0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
253b0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
253c0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
253d0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
253e0 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
253f0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
25400 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
25410 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
25420 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
25430 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
25440 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
25450 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
25460 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
25470 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
25480 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
25490 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
254a0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
254b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
254c0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
254d0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
254e0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
254f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
25500 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
25510 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
25520 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
25530 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
25540 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
25550 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
25560 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
25570 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
25580 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
25590 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
255a0 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
255b0 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
255c0 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
255d0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
255e0 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
255f0 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
25600 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
25610 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
25620 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
25630 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
25640 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
25650 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
25660 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
25670 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
25680 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
25690 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
256a0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
256b0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
256c0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
256d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
256e0 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
256f0 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
25700 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
25710 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
25720 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20  ** except that  
25730 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
25740 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
25750 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
25760 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
25770 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
25780 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
25790 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
257a0 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
257b0 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
257c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
257d0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
257e0 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
257f0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
25800 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
25810 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
25820 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
25830 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
25840 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
25850 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
25860 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
25870 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
25880 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
25890 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
258a0 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
258b0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
258c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
258d0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
258e0 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
258f0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
25900 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
25910 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
25920 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
25930 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
25940 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
25950 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
25960 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
25970 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
25980 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
25990 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
259a0 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
259b0 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
259c0 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
259d0 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
259e0 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
259f0 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
25a00 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
25a10 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
25a20 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
25a30 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
25a40 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
25a50 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
25a60 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
25a70 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
25a80 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
25a90 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  d..**.** Please 
25aa0 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
25ab0 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
25ac0 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
25ad0 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
25ae0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
25af0 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
25b00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
25b10 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
25b20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
25b30 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
25b40 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
25b50 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
25b60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
25b70 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
25b80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
25b90 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
25ba0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
25bb0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
25bc0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
25bd0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
25be0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
25bf0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
25c00 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
25c10 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
25c20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
25c30 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
25c40 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
25c50 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
25c60 73 3a 0a 2a 2a 20 5b 48 31 35 31 30 33 5d 20 5b  s:.** [H15103] [
25c70 48 31 35 31 30 36 5d 20 5b 48 31 35 31 30 39 5d  H15106] [H15109]
25c80 20 5b 48 31 35 31 31 32 5d 20 5b 48 31 35 31 31   [H15112] [H1511
25c90 35 5d 20 5b 48 31 35 31 31 38 5d 20 5b 48 31 35  5] [H15118] [H15
25ca0 31 32 31 5d 20 5b 48 31 35 31 32 34 5d 0a 2a 2a  121] [H15124].**
25cb0 20 5b 48 31 35 31 32 37 5d 20 5b 48 31 35 31 33   [H15127] [H1513
25cc0 30 5d 20 5b 48 31 35 31 33 33 5d 20 5b 48 31 35  0] [H15133] [H15
25cd0 31 33 36 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  136].*/.const vo
25ce0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
25cf0 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
25d00 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
25d10 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
25d20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
25d30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
25d40 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
25d50 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
25d60 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
25d70 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
25d80 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
25d90 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
25da0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
25db0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
25dc0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
25dd0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
25de0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
25df0 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
25e00 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
25e10 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
25e20 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
25e30 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
25e40 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
25e50 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
25e60 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
25e70 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
25e80 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
25e90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
25ea0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
25eb0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
25ec0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
25ed0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
25ee0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
25ef0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
25f00 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
25f10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
25f20 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
25f30 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
25f40 20 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30   {H16210} <S2020
25f50 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70  0>.**.** The imp
25f60 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
25f70 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
25f80 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20  ctions use this 
25f90 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
25fa0 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75  ate.** a structu
25fb0 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  re for storing t
25fc0 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
25fd0 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65  * The first time
25fe0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
25ff0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
26000 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
26010 65 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74  ed for a.** part
26020 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
26030 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74  , SQLite allocat
26040 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d  es nBytes of mem
26050 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
26060 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  that.** memory, 
26070 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
26080 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20  inter to it. On 
26090 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
260a0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
260b0 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
260c0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
260d0 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
260e0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
260f0 64 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  dex,.** the same
26100 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
26110 6e 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65  ned. The impleme
26120 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61  ntation of the a
26130 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65  ggregate can use
26140 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64  .** the returned
26150 20 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d   buffer to accum
26160 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ulate data..**.*
26170 2a 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  * SQLite automat
26180 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
26190 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65   allocated buffe
261a0 72 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  r when the aggre
261b0 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f  gate.** query co
261c0 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
261d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
261e0 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  er should be a c
261f0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
26200 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
26210 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
26220 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
26230 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
26240 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
26250 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
26260 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
26270 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
26280 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
26290 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
262a0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
262b0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
262c0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
262d0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
262e0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
262f0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
26300 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 31 31 5d 20  ts:.** [H16211] 
26310 5b 48 31 36 32 31 33 5d 20 5b 48 31 36 32 31 35  [H16213] [H16215
26320 5d 20 5b 48 31 36 32 31 37 5d 0a 2a 2f 0a 76 6f  ] [H16217].*/.vo
26330 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
26340 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
26350 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
26360 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
26370 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
26380 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
26390 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c  tions {H16240} <
263a0 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
263b0 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
263c0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
263d0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
263e0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
263f0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
26400 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
26410 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
26420 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
26430 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
26440 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
26450 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
26460 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
26470 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
26480 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
26490 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
264a0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
264b0 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a  function. {END}.
264c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
264d0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
264e0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
264f0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
26500 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
26510 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
26520 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
26530 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
26540 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 34 33 5d 0a  ts:.** [H16243].
26550 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
26560 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
26570 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
26580 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
26590 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
265a0 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
265b0 20 7b 48 31 36 32 35 30 7d 20 3c 53 36 30 36 30   {H16250} <S6060
265c0 30 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  0><S20200>.**.**
265d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
265e0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
265f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
26600 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
26610 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
26620 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
26630 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73  nection] (the 1s
26640 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
26650 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
26660 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
26670 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
26680 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
26690 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
266a0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
266b0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
266c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
266d0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
266e0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
266f0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 35 33 5d  nts:.** [H16253]
26700 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
26710 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
26720 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
26730 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
26740 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
26750 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
26760 74 61 20 7b 48 31 36 32 37 30 7d 20 3c 53 32 30  ta {H16270} <S20
26770 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  200>.**.** The f
26780 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
26790 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
267a0 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c  ed by scalar SQL
267b0 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
267c0 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
267d0 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
267e0 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
267f0 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
26800 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
26810 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
26820 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
26830 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
26840 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
26850 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
26860 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
26870 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
26880 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
26890 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79  served. This may
268a0 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72  .** be used, for
268b0 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64   example, to add
268c0 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
268d0 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73  ssion matching s
268e0 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  calar.** functio
268f0 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
26900 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
26910 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
26920 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a  n is stored as.*
26930 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
26940 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53  iated with the S
26950 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  QL value passed 
26960 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  as the regular e
26970 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74  xpression.** pat
26980 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69  tern.  The compi
26990 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
269a0 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
269b0 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
269c0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
269d0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
269e0 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65  tion so that the
269f0 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72   original patter
26a00 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73  n string.** does
26a10 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
26a20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61  recompiled on ea
26a30 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  ch invocation..*
26a40 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26a50 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
26a60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
26a70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
26a80 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
26a90 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
26aa0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
26ab0 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
26ac0 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
26ad0 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
26ae0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
26af0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
26b00 6e 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74  n. If no metadat
26b10 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a  a has been ever.
26b20 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  ** been set for 
26b30 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
26b40 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
26b50 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72  , or if the corr
26b60 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e  esponding.** fun
26b70 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
26b80 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
26b90 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
26ba0 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e  was set,.** then
26bb0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
26bc0 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61  data() returns a
26bd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
26be0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26bf0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
26c00 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
26c10 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70  he metadata.** p
26c20 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
26c30 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
26c40 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66  s the metadata f
26c50 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
26c60 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
26c70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26c80 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
26c90 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
26ca0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
26cb0 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
26cc0 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
26cd0 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
26ce0 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
26cf0 65 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20  ed..** If it is 
26d00 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
26d10 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
26d20 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66   destructor.** f
26d30 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79  unction given by
26d40 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
26d50 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  er to sqlite3_se
26d60 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a  t_auxdata() on.*
26d70 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77  * the metadata w
26d80 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
26d90 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
26da0 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
26db0 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20  .** or when the 
26dc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
26dd0 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76  mpletes, whichev
26de0 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
26df0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  **.** SQLite is 
26e00 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65  free to call the
26e10 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20   destructor and 
26e20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e  drop metadata on
26e30 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65   any.** paramete
26e40 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f  r of any functio
26e50 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20  n at any time.  
26e60 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
26e70 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
26e80 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
26e90 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
26ea0 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
26eb0 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
26ec0 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d  * In practice, m
26ed0 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65  etadata is prese
26ee0 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
26ef0 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
26f00 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
26f10 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
26f20 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
26f30 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
26f40 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
26f50 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62  s and SQL variab
26f60 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  les..**.** These
26f70 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
26f80 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
26f90 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
26fa0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
26fb0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
26fc0 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  nning..**.** Req
26fd0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
26fe0 31 36 32 37 32 5d 20 5b 48 31 36 32 37 34 5d 20  16272] [H16274] 
26ff0 5b 48 31 36 32 37 36 5d 20 5b 48 31 36 32 37 37  [H16276] [H16277
27000 5d 20 5b 48 31 36 32 37 38 5d 20 5b 48 31 36 32  ] [H16278] [H162
27010 37 39 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  79].*/.void *sql
27020 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
27030 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27040 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
27050 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
27060 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
27070 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
27080 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
27090 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
270a0 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
270b0 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
270c0 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
270d0 68 61 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20  havior {H10280} 
270e0 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30100>.**.** T
270f0 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
27100 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
27110 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
27120 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
27130 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
27140 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
27150 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
27160 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
27170 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74   If the destruct
27180 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
27190 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
271a0 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
271b0 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
271c0 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
271d0 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
271e0 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
271f0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
27200 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65   destroyed.  The
27210 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
27220 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
27230 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
27240 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
27250 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
27260 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
27270 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
27280 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
27290 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
272a0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
272b0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
272c0 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
272d0 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
272e0 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
272f0 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
27300 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
27310 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
27320 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
27330 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
27340 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
27350 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
27360 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
27370 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
27380 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
27390 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
273a0 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
273b0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
273c0 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
273d0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
273e0 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
273f0 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
27400 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32  n {H16400} <S202
27410 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
27420 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
27430 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
27440 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
27450 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
27460 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
27470 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
27480 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
27490 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
274a0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
274b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
274c0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
274d0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
274e0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
274f0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
27500 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
27510 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
27520 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
27530 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
27540 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
27550 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
27560 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
27570 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
27580 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
27590 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
275a0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
275b0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
275c0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
275d0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
275e0 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
275f0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
27600 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
27610 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
27620 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
27630 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
27640 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
27650 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
27660 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
27670 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
27680 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
27690 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
276a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
276b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
276c0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
276d0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
276e0 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
276f0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
27700 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
27710 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
27720 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
27730 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
27740 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
27750 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
27760 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
27770 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
27780 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27790 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
277a0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
277b0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
277c0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
277d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
277e0 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
277f0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
27800 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
27810 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
27820 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
27830 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
27840 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
27850 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
27860 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
27870 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
27880 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
27890 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
278a0 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  tion..** SQLite 
278b0 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
278c0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
278d0 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
278e0 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
278f0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
27900 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
27910 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
27920 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
27930 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51  ror message.  SQ
27940 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
27950 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
27960 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
27970 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27980 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
27990 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65  . SQLite.** inte
279a0 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
279b0 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
279c0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
279d0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
279e0 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
279f0 72 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  r.  If the third
27a00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
27a10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
27a20 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
27a30 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
27a40 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20  6() is negative 
27a50 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
27a60 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  s as the error.*
27a70 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65  * message all te
27a80 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68  xt up through th
27a90 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
27aa0 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68  racter..** If th
27ab0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
27ac0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
27ad0 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
27ae0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
27af0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
27b00 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
27b10 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
27b20 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
27b30 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
27b40 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
27b50 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
27b60 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
27b70 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
27b80 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
27b90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
27ba0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
27bb0 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
27bc0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
27bd0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
27be0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
27bf0 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
27c00 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
27c10 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
27c20 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
27c30 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
27c40 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
27c50 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54  thout harm..** T
27c60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
27c70 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
27c80 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
27c90 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
27ca0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
27cb0 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
27cc0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
27cd0 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20  a function.  By 
27ce0 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
27cf0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
27d00 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73  LITE_ERROR.  A s
27d10 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
27d20 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
27d30 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
27d40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
27d50 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
27d60 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
27d70 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
27d80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
27d90 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
27da0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
27db0 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
27dc0 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
27dd0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
27de0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
27df0 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70  s to long to rep
27e00 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  resent..**.** Th
27e10 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
27e20 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
27e30 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
27e40 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
27e50 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
27e60 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
27e70 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
27e80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
27e90 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
27ea0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
27eb0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
27ec0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
27ed0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
27ee0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
27ef0 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
27f00 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
27f10 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
27f20 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  d argument..** T
27f30 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
27f40 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
27f50 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
27f60 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
27f70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
27f80 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
27f90 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
27fa0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
27fb0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
27fc0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
27fd0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
27fe0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
27ff0 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
28000 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
28010 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
28020 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28030 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
28040 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  e NULL..**.** Th
28050 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
28060 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
28070 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
28080 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  ,.** sqlite3_res
28090 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20  ult_text16le(), 
280a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
280b0 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e  lt_text16be() in
280c0 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20  terfaces.** set 
280d0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
280e0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
280f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
28100 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
28110 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63  text string whic
28120 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  h is represented
28130 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31   as UTF-8, UTF-1
28140 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
28150 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  der,.** UTF-16 l
28160 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72  ittle endian, or
28170 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69   UTF-16 big endi
28180 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
28190 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65  ..** SQLite take
281a0 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
281b0 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
281c0 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
281d0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
281e0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
281f0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
28200 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74  erfaces..** If t
28210 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
28220 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
28230 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
28240 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
28250 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
28260 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
28270 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
28280 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
28290 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
282a0 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
282b0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
282c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
282d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
282e0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
282f0 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
28300 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
28310 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
28320 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
28330 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
28340 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
28350 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
28360 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
28370 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
28380 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
28390 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
283a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
283b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
283c0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
283d0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
283e0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
283f0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
28400 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
28410 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
28420 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
28430 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
28440 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
28450 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
28460 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
28470 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
28480 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
28490 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
284a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
284b0 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
284c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
284d0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
284e0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
284f0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
28500 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
28510 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
28520 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
28530 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
28540 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
28550 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
28560 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
28570 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
28580 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
28590 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
285a0 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
285b0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
285c0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  t result..** If 
285d0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
285e0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
285f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
28600 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
28610 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
28620 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
28630 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
28640 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
28650 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
28660 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
28670 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
28680 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
28690 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
286a0 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
286b0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
286c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
286d0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
286e0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
286f0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
28700 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
28710 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
28720 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
28730 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
28740 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
28750 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
28760 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
28770 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71  eter.  The.** sq
28780 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
28790 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
287a0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
287b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
287c0 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
287d0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
287e0 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
287f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
28800 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
28810 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
28820 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
28830 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
28840 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
28850 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20  ** A [protected 
28860 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
28870 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
28880 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
28890 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
288a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
288b0 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
288c0 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
288d0 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
288e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
288f0 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
28900 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
28910 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
28920 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
28930 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
28940 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
28950 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
28960 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
28970 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
28980 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
28990 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
289a0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
289b0 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
289c0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
289d0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
289e0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
289f0 0a 2a 2a 20 5b 48 31 36 34 30 33 5d 20 5b 48 31  .** [H16403] [H1
28a00 36 34 30 36 5d 20 5b 48 31 36 34 30 39 5d 20 5b  6406] [H16409] [
28a10 48 31 36 34 31 32 5d 20 5b 48 31 36 34 31 35 5d  H16412] [H16415]
28a20 20 5b 48 31 36 34 31 38 5d 20 5b 48 31 36 34 32   [H16418] [H1642
28a30 31 5d 20 5b 48 31 36 34 32 34 5d 0a 2a 2a 20 5b  1] [H16424].** [
28a40 48 31 36 34 32 37 5d 20 5b 48 31 36 34 33 30 5d  H16427] [H16430]
28a50 20 5b 48 31 36 34 33 33 5d 20 5b 48 31 36 34 33   [H16433] [H1643
28a60 36 5d 20 5b 48 31 36 34 33 39 5d 20 5b 48 31 36  6] [H16439] [H16
28a70 34 34 32 5d 20 5b 48 31 36 34 34 35 5d 20 5b 48  442] [H16445] [H
28a80 31 36 34 34 38 5d 0a 2a 2a 20 5b 48 31 36 34 35  16448].** [H1645
28a90 31 5d 20 5b 48 31 36 34 35 34 5d 20 5b 48 31 36  1] [H16454] [H16
28aa0 34 35 37 5d 20 5b 48 31 36 34 36 30 5d 20 5b 48  457] [H16460] [H
28ab0 31 36 34 36 33 5d 0a 2a 2f 0a 76 6f 69 64 20 73  16463].*/.void s
28ac0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
28ad0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
28ae0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
28af0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
28b00 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
28b10 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
28b20 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
28b30 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
28b40 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
28b50 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
28b60 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
28b70 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
28b80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
28b90 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
28ba0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
28bb0 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
28bc0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
28bd0 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
28be0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
28bf0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
28c00 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
28c10 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
28c20 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
28c30 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
28c40 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
28c50 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
28c60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28c70 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
28c80 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
28c90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28ca0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
28cb0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
28cc0 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
28cd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
28ce0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28cf0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
28d00 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
28d10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
28d20 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
28d30 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
28d40 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
28d50 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
28d60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
28d70 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
28d80 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
28d90 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
28da0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
28db0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
28dc0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
28dd0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
28de0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
28df0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
28e00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
28e10 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
28e20 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
28e30 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
28e40 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
28e50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
28e60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
28e70 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
28e80 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
28e90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
28ea0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
28eb0 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
28ec0 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
28ed0 71 75 65 6e 63 65 73 20 7b 48 31 36 36 30 30 7d  quences {H16600}
28ee0 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20300>.**.** 
28ef0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
28f00 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
28f10 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
28f20 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a  quences to the.*
28f30 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
28f40 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
28f50 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
28f60 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
28f70 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
28f80 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
28f90 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69  uence is specifi
28fa0 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74  ed as a UTF-8 st
28fb0 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
28fc0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
28fd0 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
28fe0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
28ff0 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
29000 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
29010 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
29020 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
29030 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a  . In all cases.*
29040 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61  * the name is pa
29050 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
29060 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
29070 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
29080 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d  third argument m
29090 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  ay be one of the
290a0 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49   constants [SQLI
290b0 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51  TE_UTF8],.** [SQ
290c0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 6f  LITE_UTF16LE], o
290d0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  r [SQLITE_UTF16B
290e0 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
290f0 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70  hat the user-sup
29100 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65  plied.** routine
29110 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70   expects to be p
29120 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74  assed pointers t
29130 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65  o strings encode
29140 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a  d using UTF-8,.*
29150 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d  * UTF-16 little-
29160 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
29170 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65  6 big-endian, re
29180 73 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a  spectively. The.
29190 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  ** third argumen
291a0 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20  t might also be 
291b0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 74  [SQLITE_UTF16] t
291c0 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
291d0 74 68 65 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65  the routine.** e
291e0 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20  xpects pointers 
291f0 74 6f 20 62 65 20 55 54 46 2d 31 36 20 73 74 72  to be UTF-16 str
29200 69 6e 67 73 20 69 6e 20 74 68 65 20 6e 61 74 69  ings in the nati
29210 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 20 6f  ve byte order, o
29220 72 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  r the.** argumen
29230 74 20 63 61 6e 20 62 65 20 5b 53 51 4c 49 54 45  t can be [SQLITE
29240 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
29250 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f  if the.** the ro
29260 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f  utine expects po
29270 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74  inters to 16-bit
29280 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74   word aligned st
29290 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d  rings.** of UTF-
292a0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
292b0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
292c0 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
292d0 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65  the user supplie
292e0 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  d routine must b
292f0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
29300 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e  fifth.** argumen
29310 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c  t.  If it is NUL
29320 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73  L, this is the s
29330 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20  ame as deleting 
29340 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
29350 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68   sequence (so th
29360 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74  at SQLite cannot
29370 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65   call it anymore
29380 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20  )..** Each time 
29390 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
293a0 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f  supplied functio
293b0 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  n is invoked, it
293c0 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73   is passed.** as
293d0 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d   its first param
293e0 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74  eter a copy of t
293f0 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20  he void* passed 
29400 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  as the fourth ar
29410 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
29420 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
29430 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ation() or sqlit
29440 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
29450 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  ion16()..**.** T
29460 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67  he remaining arg
29470 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70  uments to the ap
29480 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
29490 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74  ed routine are t
294a0 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65  wo strings,.** e
294b0 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20  ach represented 
294c0 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61  by a (length, da
294d0 74 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63  ta) pair and enc
294e0 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f  oded in the enco
294f0 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73  ding.** that was
29500 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
29510 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68  hird argument wh
29520 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
29530 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a   sequence was.**
29540 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e   registered. {EN
29550 44 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  D}  The applicat
29560 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c  ion defined coll
29570 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68  ation routine sh
29580 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e  ould.** return n
29590 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72  egative, zero or
295a0 20 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65   positive if the
295b0 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
295c0 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65   less than,.** e
295d0 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
295e0 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
295f0 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e  ond string. i.e.
29600 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49   (STRING1 - STRI
29610 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NG2)..**.** The 
29620 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
29630 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f  ollation_v2() wo
29640 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
29650 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
29660 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
29670 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65  at it takes an e
29680 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68  xtra argument wh
29690 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63  ich is a destruc
296a0 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63  tor for.** the c
296b0 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  ollation.  The d
296c0 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
296d0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c  led when the col
296e0 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73  lation is.** des
296f0 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61  troyed and is pa
29700 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74  ssed a copy of t
29710 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
29720 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  ter void* pointe
29730 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  r.** of the sqli
29740 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
29750 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f  tion_v2()..** Co
29760 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73  llations are des
29770 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79  troyed when they
29780 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
29790 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74  by later calls t
297a0 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69  o the.** collati
297b0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
297c0 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68  tions or when th
297d0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
297e0 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
297f0 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
29800 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
29810 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
29820 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
29830 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
29840 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
29850 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
29860 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
29870 74 73 3a 0a 2a 2a 20 5b 48 31 36 36 30 33 5d 20  ts:.** [H16603] 
29880 5b 48 31 36 36 30 34 5d 20 5b 48 31 36 36 30 36  [H16604] [H16606
29890 5d 20 5b 48 31 36 36 30 39 5d 20 5b 48 31 36 36  ] [H16609] [H166
298a0 31 32 5d 20 5b 48 31 36 36 31 35 5d 20 5b 48 31  12] [H16615] [H1
298b0 36 36 31 38 5d 20 5b 48 31 36 36 32 31 5d 0a 2a  6618] [H16621].*
298c0 2a 20 5b 48 31 36 36 32 34 5d 20 5b 48 31 36 36  * [H16624] [H166
298d0 32 37 5d 20 5b 48 31 36 36 33 30 5d 0a 2a 2f 0a  27] [H16630].*/.
298e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
298f0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
29900 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
29910 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
29920 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
29930 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
29940 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
29950 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
29960 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
29970 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
29980 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
29990 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
299a0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
299b0 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
299c0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
299d0 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
299e0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
299f0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
29a00 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
29a10 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
29a20 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
29a30 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
29a40 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
29a50 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f  e3*, .  const vo
29a60 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74  id *zName,.  int
29a70 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
29a80 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
29a90 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
29aa0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
29ab0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
29ac0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29ad0 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65   Collation Neede
29ae0 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36  d Callbacks {H16
29af0 37 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a  700} <S20300>.**
29b00 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76  .** To avoid hav
29b10 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20  ing to register 
29b20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  all collation se
29b30 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61  quences before a
29b40 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e   database.** can
29b50 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67   be used, a sing
29b60 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  le callback func
29b70 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
29b80 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a  stered with the.
29b90 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
29ba0 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63  nection] to be c
29bb0 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61  alled whenever a
29bc0 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  n undefined coll
29bd0 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
29be0 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  e is required..*
29bf0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63  *.** If the func
29c00 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
29c10 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
29c20 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
29c30 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
29c40 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
29c50 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
29c60 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
29c70 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
29c80 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
29c90 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31  ed in UTF-8. {H1
29ca0 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33  6703} If sqlite3
29cb0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
29cc0 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a  d16() is used,.*
29cd0 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20  * the names are 
29ce0 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
29cf0 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
29d00 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
29d10 2a 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68  * A call to eith
29d20 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
29d30 61 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e  aces any existin
29d40 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  g callback..**.*
29d50 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
29d60 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
29d70 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
29d80 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
29d90 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
29da0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
29db0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
29dc0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
29dd0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
29de0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
29df0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
29e00 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
29e10 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
29e20 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  on.  The third a
29e30 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
29e40 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
29e50 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
29e60 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
29e70 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
29e80 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
29e90 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
29ea0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
29eb0 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
29ec0 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54  ion required.  T
29ed0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
29ee0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
29ef0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
29f00 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
29f10 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uence..**.** The
29f20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
29f30 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
29f40 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63  er the desired c
29f50 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  ollation using.*
29f60 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
29f70 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20  e_collation()], 
29f80 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
29f90 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20  collation16()], 
29fa0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
29fb0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
29fc0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  v2()]..**.** Req
29fd0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
29fe0 31 36 37 30 32 5d 20 5b 48 31 36 37 30 34 5d 20  16702] [H16704] 
29ff0 5b 48 31 36 37 30 36 5d 0a 2a 2f 0a 69 6e 74 20  [H16706].*/.int 
2a000 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2a010 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
2a020 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
2a030 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
2a040 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
2a050 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
2a060 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
2a070 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2a080 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
2a090 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
2a0a0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2a0b0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
2a0c0 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
2a0d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
2a0e0 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
2a0f0 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
2a100 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
2a110 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
2a120 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
2a130 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
2a140 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
2a150 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
2a160 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
2a170 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
2a180 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
2a190 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
2a1a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
2a1b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2a1c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a1d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
2a1e0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
2a1f0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
2a200 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
2a210 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
2a220 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
2a230 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
2a240 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
2a250 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
2a260 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
2a270 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
2a280 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
2a290 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
2a2a0 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
2a2b0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
2a2c0 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
2a2d0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
2a2e0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
2a2f0 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
2a300 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
2a310 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
2a320 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
2a330 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
2a340 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2a350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2a360 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
2a370 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
2a380 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
2a390 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
2a3a0 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
2a3b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a3c0 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
2a3d0 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
2a3e0 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c   Time {H10530} <
2a3f0 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40410>.**.** Th
2a400 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  e sqlite3_sleep(
2a410 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  ) function cause
2a420 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  s the current th
2a430 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20  read to suspend 
2a440 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72  execution.** for
2a450 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62   at least a numb
2a460 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
2a470 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  ds specified in 
2a480 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  its parameter..*
2a490 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72  *.** If the oper
2a4a0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
2a4b0 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
2a4c0 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
2a4d0 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  h.** millisecond
2a4e0 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
2a4f0 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
2a500 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
2a510 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61  up to.** the nea
2a520 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65  rest second. The
2a530 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
2a540 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
2a550 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71   actually.** req
2a560 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20  uested from the 
2a570 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
2a580 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2a590 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
2a5a0 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72  ments this inter
2a5b0 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20  face by calling 
2a5c0 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20  the xSleep().** 
2a5d0 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
2a5e0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
2a5f0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  fs] object..**.*
2a600 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
2a610 5b 48 31 30 35 33 33 5d 20 5b 48 31 30 35 33 36  [H10533] [H10536
2a620 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2a630 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a  _sleep(int);../*
2a640 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
2a650 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72  me Of The Folder
2a660 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61   Holding Tempora
2a670 72 79 20 46 69 6c 65 73 20 7b 48 31 30 33 31 30  ry Files {H10310
2a680 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20000>.**.**
2a690 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20   If this global 
2a6a0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
2a6b0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
2a6c0 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
2a6d0 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
2a6e0 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
2a6f0 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
2a700 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69  all temporary fi
2a710 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  les.** created b
2a720 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  y SQLite will be
2a730 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
2a740 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74  directory.  If t
2a750 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
2a760 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2a770 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70  r, then SQLite p
2a780 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68  erforms a search
2a790 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69   for an appropri
2a7a0 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
2a7b0 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e   file directory.
2a7c0 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  .**.** It is not
2a7d0 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
2a7e0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
2a7f0 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68  iable in more th
2a800 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64  an one.** thread
2a810 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20   at a time.  It 
2a820 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
2a830 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
2a840 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
2a850 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  f a [database co
2a860 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
2a870 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73  ng used at the s
2a880 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65  ame time in a se
2a890 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64  parate.** thread
2a8a0 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e  ..** It is inten
2a8b0 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61  ded that this va
2a8c0 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e  riable be set on
2a8d0 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ce.** as part of
2a8e0 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
2a8f0 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f  ization and befo
2a900 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  re any SQLite in
2a910 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69  terface.** routi
2a920 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61  nes have been ca
2a930 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68  lled and that th
2a940 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61  is variable rema
2a950 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  in unchanged.** 
2a960 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a  thereafter..**.*
2a970 2a 20 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  * The [temp_stor
2a980 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2a990 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74  ma] may modify t
2a9a0 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64  his variable and
2a9b0 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20   cause.** it to 
2a9c0 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
2a9d0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2a9e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20  qlite3_malloc]. 
2a9f0 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a   Furthermore,.**
2aa00 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
2aa10 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
2aa20 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
2aa30 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
2aa40 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
2aa50 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
2aa60 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
2aa70 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
2aa80 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
2aa90 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
2aaa0 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
2aab0 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
2aac0 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
2aad0 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
2aae0 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
2aaf0 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
2ab00 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
2ab10 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
2ab20 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
2ab30 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
2ab40 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
2ab50 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
2ab60 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
2ab70 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
2ab80 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
2ab90 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
2aba0 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
2abb0 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ided..*/.SQLITE_
2abc0 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c  EXTERN char *sql
2abd0 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
2abe0 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ory;../*.** CAPI
2abf0 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41  3REF: Test For A
2ac00 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20  uto-Commit Mode 
2ac10 7b 48 31 32 39 33 30 7d 20 3c 53 36 30 32 30 30  {H12930} <S60200
2ac20 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
2ac30 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d  autocommit mode}
2ac40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2ac50 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
2ac60 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  t() interface re
2ac70 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
2ac80 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
2ac90 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
2aca0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
2acb0 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
2acc0 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
2acd0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 75  espectively.  Au
2ace0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2acf0 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a   on by default..
2ad00 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  ** Autocommit mo
2ad10 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
2ad20 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  y a [BEGIN] stat
2ad30 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f  ement..** Autoco
2ad40 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d  mmit mode is re-
2ad50 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f  enabled by a [CO
2ad60 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
2ad70 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65  CK]..**.** If ce
2ad80 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65  rtain kinds of e
2ad90 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61  rrors occur on a
2ada0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
2adb0 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d  n a multi-statem
2adc0 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  ent.** transacti
2add0 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75  on (errors inclu
2ade0 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c  ding [SQLITE_FUL
2adf0 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  L], [SQLITE_IOER
2ae00 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  R],.** [SQLITE_N
2ae10 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  OMEM], [SQLITE_B
2ae20 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  USY], and [SQLIT
2ae30 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68  E_INTERRUPT]) th
2ae40 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61  en the.** transa
2ae50 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72  ction might be r
2ae60 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
2ae70 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f  atically.  The o
2ae80 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69  nly way to.** fi
2ae90 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53  nd out whether S
2aea0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
2aeb0 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
2aec0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2aed0 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  after.** an erro
2aee0 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73  r is to use this
2aef0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2af00 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
2af10 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
2af20 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
2af30 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2af40 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  .** connection w
2af50 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
2af60 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68  e is running, th
2af70 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
2af80 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  lue.** is undefi
2af90 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ned..**.** Requi
2afa0 72 65 6d 65 6e 74 73 3a 20 5b 48 31 32 39 33 31  rements: [H12931
2afb0 5d 20 5b 48 31 32 39 33 32 5d 20 5b 48 31 32 39  ] [H12932] [H129
2afc0 33 33 5d 20 5b 48 31 32 39 33 34 5d 0a 2a 2f 0a  33] [H12934].*/.
2afd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
2afe0 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
2aff0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
2b000 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
2b010 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
2b020 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
2b030 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 32 30 7d  atement {H13120}
2b040 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60600>.**.** 
2b050 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68  The sqlite3_db_h
2b060 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20  andle interface 
2b070 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74  returns the [dat
2b080 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b090 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77  ] handle.** to w
2b0a0 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64  hich a [prepared
2b0b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f   statement] belo
2b0c0 6e 67 73 2e 20 20 54 68 65 20 5b 64 61 74 61 62  ngs.  The [datab
2b0d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
2b0e0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2b0f0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
2b100 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61   is the same [da
2b110 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b120 6e 5d 20 74 68 61 74 20 77 61 73 20 74 68 65 20  n] that was the 
2b130 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
2b140 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
2b150 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2b160 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72  call (or its var
2b170 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20  iants) that was 
2b180 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74  used to.** creat
2b190 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
2b1a0 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
2b1b0 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ce..**.** Requir
2b1c0 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 32 33 5d  ements: [H13123]
2b1d0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
2b1e0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73  ite3_db_handle(s
2b1f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2b200 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b210 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72  Find the next pr
2b220 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b230 20 7b 48 31 33 31 34 30 7d 20 3c 53 36 30 36 30   {H13140} <S6060
2b240 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0>.**.** This in
2b250 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b260 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2b270 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
2b280 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
2b290 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
2b2a0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
2b2b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b2c0 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 70 53 74  on] pDb.  If pSt
2b2d0 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68  mt is NULL.** th
2b2e0 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  en this interfac
2b2f0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2b300 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74  ter to the first
2b310 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b320 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ent.** associate
2b330 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62  d with the datab
2b340 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70  ase connection p
2b350 44 62 2e 20 20 49 66 20 6e 6f 20 70 72 65 70 61  Db.  If no prepa
2b360 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2b370 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63   satisfies the c
2b380 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69  onditions of thi
2b390 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65  s routine, it re
2b3a0 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  turns NULL..**.*
2b3b0 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20  * The [database 
2b3c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e  connection] poin
2b3d0 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20  ter D in a call 
2b3e0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e  to.** [sqlite3_n
2b3f0 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d  ext_stmt(D,S)] m
2b400 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20  ust refer to an 
2b410 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a  open database.**
2b420 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20   connection and 
2b430 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75  in particular mu
2b440 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c  st not be a NULL
2b450 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2b460 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48  Requirements: [H
2b470 31 33 31 34 33 5d 20 5b 48 31 33 31 34 36 5d 20  13143] [H13146] 
2b480 5b 48 31 33 31 34 39 5d 20 5b 48 31 33 31 35 32  [H13149] [H13152
2b490 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d  ].*/.sqlite3_stm
2b4a0 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  t *sqlite3_next_
2b4b0 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44  stmt(sqlite3 *pD
2b4c0 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  b, sqlite3_stmt 
2b4d0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2b4e0 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74  CAPI3REF: Commit
2b4f0 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f   And Rollback No
2b500 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
2b510 61 63 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c 53  acks {H12950} <S
2b520 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  60400>.**.** The
2b530 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
2b540 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
2b550 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
2b560 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
2b570 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
2b580 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
2b590 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49  action is [COMMI
2b5a0 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a  T | committed]..
2b5b0 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
2b5c0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
2b5d0 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
2b5e0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
2b5f0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2b600 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b610 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
2b620 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  n..** The sqlite
2b630 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2b640 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
2b650 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
2b660 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
2b670 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2b680 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
2b690 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c  n is [ROLLBACK |
2b6a0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a   rolled back]..*
2b6b0 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73  * Any callback s
2b6c0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
2b6d0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2b6e0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
2b6f0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2b700 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b710 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2b720 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72  ..** The pArg ar
2b730 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64  gument is passed
2b740 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
2b750 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 20  callback..** If 
2b760 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
2b770 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
2b780 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
2b790 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  on-zero,.** then
2b7a0 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
2b7b0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
2b7c0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
2b7d0 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
2b7e0 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
2b7f0 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
2b800 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65  ts.** pArg value
2b810 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
2b820 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73  therwise NULL is
2b830 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2b840 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d   The callback im
2b850 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
2b860 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
2b870 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
2b880 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
2b890 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
2b8a0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63  at invoked the c
2b8b0 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63  allback.  Any ac
2b8c0 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
2b8d0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
2b8e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
2b8f0 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
2b900 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
2b910 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
2b920 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2b930 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
2b940 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74  gered the commit
2b950 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  .** or rollback 
2b960 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73  hook in the firs
2b970 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65  t place..** Note
2b980 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
2b990 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2b9a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2b9b0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
2b9c0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
2b9d0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
2b9e0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
2b9f0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
2ba00 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
2ba10 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e   Registering a N
2ba20 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  ULL function dis
2ba30 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61  ables the callba
2ba40 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ck..**.** When t
2ba50 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63  he commit hook c
2ba60 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
2ba70 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
2ba80 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70  e [COMMIT].** op
2ba90 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77  eration is allow
2baa0 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e  ed to continue n
2bab0 6f 72 6d 61 6c 6c 79 2e 20 20 49 66 20 74 68 65  ormally.  If the
2bac0 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20   commit hook.** 
2bad0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
2bae0 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d  , then the [COMM
2baf0 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64  IT] is converted
2bb00 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43   into a [ROLLBAC
2bb10 4b 5d 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62  K]..** The rollb
2bb20 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f  ack hook is invo
2bb30 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63  ked on a rollbac
2bb40 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66  k that results f
2bb50 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20  rom a commit.** 
2bb60 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e  hook returning n
2bb70 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73  on-zero, just as
2bb80 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74   it would be wit
2bb90 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c  h any other roll
2bba0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  back..**.** For 
2bbb0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
2bbc0 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e  this API, a tran
2bbd0 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20  saction is said 
2bbe0 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20  to have been.** 
2bbf0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61  rolled back if a
2bc00 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c  n explicit "ROLL
2bc10 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20  BACK" statement 
2bc20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a  is executed, or.
2bc30 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63  ** an error or c
2bc40 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73  onstraint causes
2bc50 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c   an implicit rol
2bc60 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a  lback to occur..
2bc70 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  ** The rollback 
2bc80 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
2bc90 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
2bca0 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61  nsaction is.** a
2bcb0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
2bcc0 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65  led back because
2bcd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2bce0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
2bcf0 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62  ed..** The rollb
2bd00 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
2bd10 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
2bd20 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
2bd30 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ** rolled back b
2bd40 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20  ecause a commit 
2bd50 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65  callback returne
2bd60 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c  d non-zero..** <
2bd70 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74  todo> Check on t
2bd80 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  his </todo>.**.*
2bd90 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
2bda0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2bdb0 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ook()] interface
2bdc0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
2bdd0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 35 31  ents:.** [H12951
2bde0 5d 20 5b 48 31 32 39 35 32 5d 20 5b 48 31 32 39  ] [H12952] [H129
2bdf0 35 33 5d 20 5b 48 31 32 39 35 34 5d 20 5b 48 31  53] [H12954] [H1
2be00 32 39 35 35 5d 0a 2a 2a 20 5b 48 31 32 39 36 31  2955].** [H12961
2be10 5d 20 5b 48 31 32 39 36 32 5d 20 5b 48 31 32 39  ] [H12962] [H129
2be20 36 33 5d 20 5b 48 31 32 39 36 34 5d 0a 2a 2f 0a  63] [H12964].*/.
2be30 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2be40 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
2be50 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
2be60 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
2be70 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
2be80 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
2be90 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
2bea0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
2beb0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
2bec0 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
2bed0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48  ion Callbacks {H
2bee0 31 32 39 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a  12970} <S60400>.
2bef0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2bf00 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20  3_update_hook() 
2bf10 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
2bf20 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
2bf30 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
2bf40 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2bf50 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69  nnection] identi
2bf60 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
2bf70 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
2bf80 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
2bf90 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70  ever a row is up
2bfa0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
2bfb0 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41  or deleted..** A
2bfc0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
2bfd0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
2bfe0 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ll to this funct
2bff0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ion.** for the s
2c000 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
2c010 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
2c020 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  idden..**.** The
2c030 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2c040 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
2c050 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f   the function to
2c060 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a   invoke when a.*
2c070 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  * row is updated
2c080 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
2c090 6c 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69  leted..** The fi
2c0a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2c0b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
2c0c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
2c0d0 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
2c0e0 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  to sqlite3_updat
2c0f0 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65  e_hook()..** The
2c100 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b   second callback
2c110 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
2c120 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45   of [SQLITE_INSE
2c130 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c  RT], [SQLITE_DEL
2c140 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  ETE],.** or [SQL
2c150 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70  ITE_UPDATE], dep
2c160 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70  ending on the op
2c170 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75  eration that cau
2c180 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  sed the callback
2c190 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  .** to be invoke
2c1a0 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  d..** The third 
2c1b0 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d  and fourth argum
2c1c0 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ents to the call
2c1d0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69  back contain poi
2c1e0 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20  nters to the.** 
2c1f0 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62  database and tab
2c200 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69  le name containi
2c210 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20  ng the affected 
2c220 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61  row..** The fina
2c230 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
2c240 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77  eter is the [row
2c250 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a  id] of the row..
2c260 2a 2a 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f  ** In the case o
2c270 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69  f an update, thi
2c280 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  s is the [rowid]
2c290 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74   after the updat
2c2a0 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a  e takes place..*
2c2b0 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20  *.** The update 
2c2c0 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
2c2d0 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
2c2e0 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
2c2f0 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
2c300 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
2c310 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
2c320 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20  equence)..**.** 
2c330 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  In the current i
2c340 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74  mplementation, t
2c350 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a  he update hook.*
2c360 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  * is not invoked
2c370 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f   when duplicatio
2c380 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  n rows are delet
2c390 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e  ed because of an
2c3a0 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54  .** [ON CONFLICT
2c3b0 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52   | ON CONFLICT R
2c3c0 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20  EPLACE] clause. 
2c3d0 20 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61   Nor is the upda
2c3e0 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b  te hook.** invok
2c3f0 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65  ed when rows are
2c400 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74   deleted using t
2c410 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  he [truncate opt
2c420 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  imization]..** T
2c430 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65  he exceptions de
2c440 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61  fined in this pa
2c450 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68  ragraph might ch
2c460 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
2c470 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
2c480 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
2c490 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70   update hook imp
2c4a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
2c4b0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
2c4c0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
2c4d0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
2c4e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
2c4f0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70  t invoked the up
2c500 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20  date hook.  Any 
2c510 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f  actions.** to mo
2c520 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
2c530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
2c540 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e  t be deferred un
2c550 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a  til after the.**
2c560 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74   completion of t
2c570 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
2c580 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ()] call that tr
2c590 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61  iggered the upda
2c5a0 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65  te hook..** Note
2c5b0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
2c5c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2c5d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c5e0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
2c5f0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
2c600 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
2c610 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
2c620 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
2c630 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
2c640 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63   If another func
2c650 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75  tion was previou
2c660 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20  sly registered, 
2c670 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a  its pArg value.*
2c680 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  * is returned.  
2c690 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69  Otherwise NULL i
2c6a0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2c6b0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
2c6c0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2c6d0 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ook()] and [sqli
2c6e0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2c6f0 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  k()].** interfac
2c700 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  es..**.** Requir
2c710 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39  ements:.** [H129
2c720 37 31 5d 20 5b 48 31 32 39 37 33 5d 20 5b 48 31  71] [H12973] [H1
2c730 32 39 37 35 5d 20 5b 48 31 32 39 37 37 5d 20 5b  2975] [H12977] [
2c740 48 31 32 39 37 39 5d 20 5b 48 31 32 39 38 31 5d  H12979] [H12981]
2c750 20 5b 48 31 32 39 38 33 5d 20 5b 48 31 32 39 38   [H12983] [H1298
2c760 36 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  6].*/.void *sqli
2c770 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
2c780 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2c790 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
2c7a0 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
2c7b0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
2c7c0 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
2c7d0 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
2c7e0 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
2c7f0 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
2c800 65 64 20 50 61 67 65 72 20 43 61 63 68 65 20 7b  ed Pager Cache {
2c810 48 31 30 33 33 30 7d 20 3c 53 33 30 39 30 30 3e  H10330} <S30900>
2c820 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73  .** KEYWORDS: {s
2c830 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a  hared cache}.**.
2c840 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2c850 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
2c860 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
2c870 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2c880 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
2c890 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
2c8a0 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
2c8b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c8c0 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
2c8d0 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
2c8e0 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
2c8f0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
2c900 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
2c910 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
2c920 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
2c930 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a  ent is false..**
2c940 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e  .** Cache sharin
2c950 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64  g is enabled and
2c960 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e   disabled for an
2c970 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
2c980 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68  .** This is a ch
2c990 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74  ange as of SQLit
2c9a0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e  e version 3.5.0.
2c9b0 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f   In prior versio
2c9c0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a  ns of SQLite,.**
2c9d0 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61   sharing was ena
2c9e0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
2c9f0 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64   for each thread
2ca00 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
2ca10 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61  ** The cache sha
2ca20 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79  ring mode set by
2ca30 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2ca40 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73  effects all subs
2ca50 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
2ca60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
2ca70 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2ca80 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73  en_v2()], and [s
2ca90 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2caa0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61  ..** Existing da
2cab0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2cac0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20  ns continue use 
2cad0 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  the sharing mode
2cae0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20  .** that was in 
2caf0 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69  effect at the ti
2cb00 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65  me they were ope
2cb10 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75  ned..**.** Virtu
2cb20 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74  al tables cannot
2cb30 20 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20   be used with a 
2cb40 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 57  shared cache.  W
2cb50 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  hen shared.** ca
2cb60 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  che is enabled, 
2cb70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2cb80 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50  ate_module()] AP
2cb90 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74  I used to regist
2cba0 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  er.** virtual ta
2cbb0 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73  bles will always
2cbc0 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
2cbd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
2cbe0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
2cbf0 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
2cc00 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61  ed cache was ena
2cc10 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
2cc20 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2cc30 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64  .  An [error cod
2cc40 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f  e] is returned o
2cc50 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
2cc60 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  Shared cache is 
2cc70 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
2cc80 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69  ult. But this mi
2cc90 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ght change in.**
2cca0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
2ccb0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70   of SQLite.  App
2ccc0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63  lications that c
2ccd0 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64  are about shared
2cce0 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e  .** cache settin
2ccf0 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20  g should set it 
2cd00 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a  explicitly..**.*
2cd10 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51  * See Also:  [SQ
2cd20 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68  Lite Shared-Cach
2cd30 65 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52 65  e Mode].**.** Re
2cd40 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30  quirements: [H10
2cd50 33 33 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b 48  331] [H10336] [H
2cd60 31 30 33 33 37 5d 20 5b 48 31 30 33 33 39 5d 0a  10337] [H10339].
2cd70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
2cd80 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
2cd90 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  he(int);../*.** 
2cda0 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70  CAPI3REF: Attemp
2cdb0 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d  t To Free Heap M
2cdc0 65 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 3c  emory {H17340} <
2cdd0 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30220>.**.** Th
2cde0 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  e sqlite3_releas
2cdf0 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72  e_memory() inter
2ce00 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
2ce10 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a   free N bytes.**
2ce20 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
2ce30 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20  by deallocating 
2ce40 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
2ce50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
2ce60 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20  .** held by the 
2ce70 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79  database library
2ce80 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20  . {END}  Memory 
2ce90 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61  used to cache da
2cea0 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20  tabase.** pages 
2ceb0 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  to improve perfo
2cec0 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61  rmance is an exa
2ced0 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65  mple of non-esse
2cee0 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  ntial memory..**
2cef0 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
2cf00 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
2cf10 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2cf20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
2cf30 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d  reed,.** which m
2cf40 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
2cf50 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d  less than the am
2cf60 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
2cf70 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
2cf80 74 73 3a 20 5b 48 31 37 33 34 31 5d 20 5b 48 31  ts: [H17341] [H1
2cf90 37 33 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  7342].*/.int sql
2cfa0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2cfb0 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  ory(int);../*.**
2cfc0 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73   CAPI3REF: Impos
2cfd0 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61  e A Limit On Hea
2cfe0 70 20 53 69 7a 65 20 7b 48 31 37 33 35 30 7d 20  p Size {H17350} 
2cff0 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30220>.**.** T
2d000 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  he sqlite3_soft_
2d010 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74  heap_limit() int
2d020 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20  erface places a 
2d030 22 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20  "soft" limit.** 
2d040 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  on the amount of
2d050 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61   heap memory tha
2d060 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74  t may be allocat
2d070 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  ed by SQLite..**
2d080 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20   If an internal 
2d090 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65  allocation is re
2d0a0 71 75 65 73 74 65 64 20 74 68 61 74 20 77 6f 75  quested that wou
2d0b0 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a  ld exceed the.**
2d0c0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2d0d0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  , [sqlite3_relea
2d0e0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20  se_memory()] is 
2d0f0 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a  invoked one or.*
2d100 2a 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  * more times to 
2d110 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61  free up some spa
2d120 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c  ce before the al
2d130 6c 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66  location is perf
2d140 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ormed..**.** The
2d150 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64   limit is called
2d160 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65   "soft", because
2d170 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c   if [sqlite3_rel
2d180 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a  ease_memory()].*
2d190 2a 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75  * cannot free su
2d1a0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
2d1b0 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c  to prevent the l
2d1c0 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20  imit from being 
2d1d0 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65  exceeded,.** the
2d1e0 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63   memory is alloc
2d1f0 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20  ated anyway and 
2d200 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72  the current oper
2d210 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a  ation proceeds..
2d220 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65  **.** A negative
2d230 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66   or zero value f
2d240 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20  or N means that 
2d250 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74  there is no soft
2d260 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a   heap limit and.
2d270 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** [sqlite3_rele
2d280 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69  ase_memory()] wi
2d290 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ll only be calle
2d2a0 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73  d when memory is
2d2b0 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54   exhausted..** T
2d2c0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
2d2d0 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
2d2e0 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f  ap limit is zero
2d2f0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
2d300 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f  akes a best effo
2d310 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20  rt to honor the 
2d320 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e  soft heap limit.
2d330 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73  .** But if the s
2d340 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63  oft heap limit c
2d350 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64  annot be honored
2d360 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c  , execution will
2d370 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74  .** continue wit
2d380 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f  hout error or no
2d390 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69  tification.  Thi
2d3a0 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d  s is why the lim
2d3b0 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20  it is.** called 
2d3c0 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20  a "soft" limit. 
2d3d0 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20   It is advisory 
2d3e0 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  only..**.** Prio
2d3f0 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
2d400 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20  ion 3.5.0, this 
2d410 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e  routine only con
2d420 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d  strained the mem
2d430 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64  ory.** allocated
2d440 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
2d450 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74  ead - the same t
2d460 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
2d470 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
2d480 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20  uns.  Beginning 
2d490 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
2d4a0 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73  ion 3.5.0, the s
2d4b0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
2d4c0 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20  s.** applied to 
2d4d0 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65  all threads. The
2d4e0 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
2d4f0 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
2d500 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61  ap limit.** is a
2d510 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  n upper bound on
2d520 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72   the total memor
2d530 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
2d540 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e   all threads. In
2d550 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  .** version 3.5.
2d560 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  0 there is no me
2d570 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69  chanism for limi
2d580 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73  ting the heap us
2d590 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76  age for.** indiv
2d5a0 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a  idual threads..*
2d5b0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
2d5c0 73 3a 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20 5b  s:.** [H16351] [
2d5d0 48 31 36 33 35 32 5d 20 5b 48 31 36 33 35 33 5d  H16352] [H16353]
2d5e0 20 5b 48 31 36 33 35 34 5d 20 5b 48 31 36 33 35   [H16354] [H1635
2d5f0 35 5d 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a 76  5] [H16358].*/.v
2d600 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  oid sqlite3_soft
2d610 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29  _heap_limit(int)
2d620 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d630 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64  F: Extract Metad
2d640 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75  ata About A Colu
2d650 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b 48  mn Of A Table {H
2d660 31 32 38 35 30 7d 20 3c 53 36 30 33 30 30 3e 0a  12850} <S60300>.
2d670 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2d680 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64  ne returns metad
2d690 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63  ata about a spec
2d6a0 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61  ific column of a
2d6b0 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74   specific.** dat
2d6c0 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65  abase table acce
2d6d0 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65  ssible using the
2d6e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2d6f0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
2d700 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
2d710 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72  irst function ar
2d720 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
2d730 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e  e column is iden
2d740 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65  tified by the se
2d750 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20  cond, third and 
2d760 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2d770 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e  s to.** this fun
2d780 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e  ction. The secon
2d790 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65  d parameter is e
2d7a0 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f  ither the name o
2d7b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
2d7c0 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20  * (i.e. "main", 
2d7d0 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74  "temp" or an att
2d7e0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20  ached database) 
2d7f0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73  containing the s
2d800 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c  pecified.** tabl
2d810 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74  e or NULL. If it
2d820 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61   is NULL, then a
2d830 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61  ll attached data
2d840 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68  bases are search
2d850 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61  ed.** for the ta
2d860 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61  ble using the sa
2d870 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65  me algorithm use
2d880 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
2d890 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72  e engine to.** r
2d8a0 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69  esolve unqualifi
2d8b0 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e  ed table referen
2d8c0 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ces..**.** The t
2d8d0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
2d8e0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
2d8f0 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  is function are 
2d900 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  the table and co
2d910 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20  lumn.** name of 
2d920 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75  the desired colu
2d930 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  mn, respectively
2d940 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65  . Neither of the
2d950 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  se parameters.**
2d960 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   may be NULL..**
2d970 0a 2a 2a 20 4d 65 74 61 64 61 74 61 20 69 73 20  .** Metadata is 
2d980 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74  returned by writ
2d990 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ing to the memor
2d9a0 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73  y locations pass
2d9b0 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a  ed as the 5th.**
2d9c0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
2d9d0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
2d9e0 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79  is function. Any
2d9f0 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65   of these argume
2da00 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55  nts may be.** NU
2da10 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  LL, in which cas
2da20 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
2da30 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d  ing element of m
2da40 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74  etadata is omitt
2da50 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed..**.** <block
2da60 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2da70 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2da80 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74  <tr><th> Paramet
2da90 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62  er <th> Output<b
2daa0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73  r>Type <th>  Des
2dab0 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  cription.**.** <
2dac0 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e  tr><td> 5th <td>
2dad0 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64   const char* <td
2dae0 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c  > Data type.** <
2daf0 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e  tr><td> 6th <td>
2db00 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64   const char* <td
2db10 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c  > Name of defaul
2db20 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  t collation sequ
2db30 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ence.** <tr><td>
2db40 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   7th <td> int   
2db50 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
2db60 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20  if column has a 
2db70 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
2db80 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  int.** <tr><td> 
2db90 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  8th <td> int    
2dba0 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
2dbb0 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74  f column is part
2dbc0 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20   of the PRIMARY 
2dbd0 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  KEY.** <tr><td> 
2dbe0 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  9th <td> int    
2dbf0 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
2dc00 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54  f column is [AUT
2dc10 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c  OINCREMENT].** <
2dc20 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
2dc30 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
2dc40 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
2dc50 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72  d to by the char
2dc60 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72  acter pointers r
2dc70 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a  eturned for the.
2dc80 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74  ** declaration t
2dc90 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f  ype and collatio
2dca0 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61  n sequence is va
2dcb0 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74  lid only until t
2dcc0 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20  he next.** call 
2dcd0 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50  to any SQLite AP
2dce0 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  I function..**.*
2dcf0 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69  * If the specifi
2dd00 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75  ed table is actu
2dd10 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20  ally a view, an 
2dd20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2dd30 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2dd40 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
2dd50 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69   column is "rowi
2dd60 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72  d", "oid" or "_r
2dd70 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a  owid_" and an.**
2dd80 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
2dd90 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61  Y KEY] column ha
2dda0 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c  s been explicitl
2ddb0 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e  y declared, then
2ddc0 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70   the output.** p
2ddd0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
2dde0 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63  t for the explic
2ddf0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
2de00 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69  lumn. If there i
2de10 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74  s no.** explicit
2de20 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54  ly declared [INT
2de30 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
2de40 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74  ] column, then t
2de50 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
2de60 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
2de70 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
2de80 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64  * <pre>.**     d
2de90 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47  ata type: "INTEG
2dea0 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61  ER".**     colla
2deb0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22  tion sequence: "
2dec0 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e  BINARY".**     n
2ded0 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20  ot null: 0.**   
2dee0 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31    primary key: 1
2def0 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63  .**     auto inc
2df00 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70  rement: 0.** </p
2df10 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  re>.**.** This f
2df20 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64  unction may load
2df30 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68   one or more sch
2df40 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61  emas from databa
2df50 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a  se files. If an.
2df60 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  ** error occurs 
2df70 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63  during this proc
2df80 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72  ess, or if the r
2df90 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f  equested table o
2dfa0 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e  r column.** cann
2dfb0 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20  ot be found, an 
2dfc0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2dfd0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20  returned and an 
2dfe0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65  error message le
2dff0 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61  ft.** in the [da
2e000 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e010 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65  n] (to be retrie
2e020 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ved using sqlite
2e030 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a  3_errmsg())..**.
2e040 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f  ** This API is o
2e050 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
2e060 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
2e070 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
2e080 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
2e090 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2e0a0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
2e0b0 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
2e0c0 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
2e0d0 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e  te3_table_column
2e0e0 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c  _metadata(.  sql
2e0f0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2e100 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e           /* Conn
2e110 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f  ection handle */
2e120 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2e130 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f  DbName,        /
2e140 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20  * Database name 
2e150 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e  or NULL */.  con
2e160 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e  st char *zTableN
2e170 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c  ame,     /* Tabl
2e180 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73  e name */.  cons
2e190 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e  t char *zColumnN
2e1a0 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d  ame,    /* Colum
2e1b0 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72  n name */.  char
2e1c0 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54   const **pzDataT
2e1d0 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55  ype,    /* OUTPU
2e1e0 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61  T: Declared data
2e1f0 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20   type */.  char 
2e200 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65  const **pzCollSe
2e210 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  q,     /* OUTPUT
2e220 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  : Collation sequ
2e230 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69  ence name */.  i
2e240 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20  nt *pNotNull,   
2e250 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
2e260 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f  TPUT: True if NO
2e270 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
2e280 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e  t exists */.  in
2e290 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20  t *pPrimaryKey, 
2e2a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
2e2b0 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
2e2c0 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a  umn part of PK *
2e2d0 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e  /.  int *pAutoin
2e2e0 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  c               
2e2f0 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
2e300 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74  if column is aut
2e310 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29  o-increment */.)
2e320 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e330 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e  F: Load An Exten
2e340 73 69 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53  sion {H12600} <S
2e350 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  20500>.**.** Thi
2e360 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64  s interface load
2e370 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65  s an SQLite exte
2e380 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72  nsion library fr
2e390 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c  om the named fil
2e3a0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31  e..**.** {H12601
2e3b0 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f  } The sqlite3_lo
2e3c0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
2e3d0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2e3e0 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20  s to load an.** 
2e3f0 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20           SQLite 
2e400 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
2e410 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74  y contained in t
2e420 68 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a  he file zFile..*
2e430 2a 0a 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 68  *.** {H12602} Th
2e440 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73  e entry point is
2e450 20 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48   zProc..**.** {H
2e460 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79  12603} zProc may
2e470 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20   be 0, in which 
2e480 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66  case the name of
2e490 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   the entry point
2e4a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
2e4b0 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65  aults to "sqlite
2e4c0 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74  3_extension_init
2e4d0 22 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34  "..**.** {H12604
2e4e0 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f  } The sqlite3_lo
2e4f0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
2e500 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72  nterface shall r
2e510 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
2e520 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e    [SQLITE_OK] on
2e530 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
2e540 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
2e550 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
2e560 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  ong..**.** {H126
2e570 30 35 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20  05} If an error 
2e580 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72  occurs and pzErr
2e590 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68  Msg is not 0, th
2e5a0 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  en the.**       
2e5b0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64     [sqlite3_load
2e5c0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e  _extension()] in
2e5d0 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74  terface shall at
2e5e0 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20  tempt to.**     
2e5f0 20 20 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72       fill *pzErr
2e600 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d  Msg with error m
2e610 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72  essage text stor
2e620 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ed in memory.** 
2e630 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65           obtaine
2e640 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2e650 6d 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d  malloc()]. {END}
2e660 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75    The calling fu
2e670 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
2e680 20 20 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74     should free t
2e690 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61  his memory by ca
2e6a0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  lling [sqlite3_f
2e6b0 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ree()]..**.** {H
2e6c0 31 32 36 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e  12606} Extension
2e6d0 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65   loading must be
2e6e0 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a   enabled using.*
2e6f0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2e700 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
2e710 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69  extension()] pri
2e720 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68  or to calling th
2e730 69 73 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20  is API,.**      
2e740 20 20 20 20 6f 74 68 65 72 77 69 73 65 20 61 6e      otherwise an
2e750 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
2e760 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  eturned..*/.int 
2e770 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
2e780 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  ension(.  sqlite
2e790 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2e7a0 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65  /* Load the exte
2e7b0 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20  nsion into this 
2e7c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e7d0 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ion */.  const c
2e7e0 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f  har *zFile,    /
2e7f0 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68  * Name of the sh
2e800 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e  ared library con
2e810 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f  taining extensio
2e820 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  n */.  const cha
2e830 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20  r *zProc,    /* 
2e840 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65  Entry point.  De
2e850 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65  rived from zFile
2e860 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20   if 0 */.  char 
2e870 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20  **pzErrMsg      
2e880 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65   /* Put error me
2e890 73 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f  ssage here if no
2e8a0 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  t 0 */.);../*.**
2e8b0 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
2e8c0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
2e8d0 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b  ension Loading {
2e8e0 48 31 32 36 32 30 7d 20 3c 53 32 30 35 30 30 3e  H12620} <S20500>
2e8f0 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74  .**.** So as not
2e900 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74   to open securit
2e910 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72  y holes in older
2e920 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
2e930 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70  at are.** unprep
2e940 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74  ared to deal wit
2e950 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  h extension load
2e960 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65  ing, and as a me
2e970 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67  ans of disabling
2e980 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  .** extension lo
2e990 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c  ading while eval
2e9a0 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65  uating user-ente
2e9b0 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c  red SQL, the fol
2e9c0 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73  lowing API.** is
2e9d0 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72   provided to tur
2e9e0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  n the [sqlite3_l
2e9f0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
2ea00 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e   mechanism on an
2ea10 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74  d off..**.** Ext
2ea20 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69  ension loading i
2ea30 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74  s off by default
2ea40 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38  . See ticket #18
2ea50 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32  63..**.** {H1262
2ea60 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69  1} Call the sqli
2ea70 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
2ea80 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74  extension() rout
2ea90 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d  ine with onoff==
2eaa0 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  1.**          to
2eab0 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20   turn extension 
2eac0 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63  loading on and c
2ead0 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66  all it with onof
2eae0 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20  f==0 to turn.** 
2eaf0 20 20 20 20 20 20 20 20 20 69 74 20 62 61 63 6b           it back
2eb00 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a   off again..**.*
2eb10 2a 20 7b 48 31 32 36 32 32 7d 20 45 78 74 65 6e  * {H12622} Exten
2eb20 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20  sion loading is 
2eb30 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  off by default..
2eb40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
2eb50 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
2eb60 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62  sion(sqlite3 *db
2eb70 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
2eb80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
2eb90 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61  utomatically Loa
2eba0 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73 20  d An Extensions 
2ebb0 7b 48 31 32 36 34 30 7d 20 3c 53 32 30 35 30 30  {H12640} <S20500
2ebc0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  >.**.** This API
2ebd0 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20   can be invoked 
2ebe0 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74  at program start
2ebf0 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72  up in order to r
2ec00 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  egister.** one o
2ec10 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c  r more staticall
2ec20 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69  y linked extensi
2ec30 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  ons that will be
2ec40 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f   available.** to
2ec50 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 61   all new [databa
2ec60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e  se connections].
2ec70 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69   {END}.**.** Thi
2ec80 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
2ec90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2eca0 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61  e extension in a
2ecb0 6e 20 61 72 72 61 79 20 74 68 61 74 20 69 73 0a  n array that is.
2ecc0 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
2ecd0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2ece0 28 29 5d 2e 20 20 49 66 20 79 6f 75 20 72 75 6e  ()].  If you run
2ecf0 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 63   a memory leak c
2ed00 68 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75  hecker.** on you
2ed10 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74  r program and it
2ed20 20 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20   reports a leak 
2ed30 62 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 20  because of this 
2ed40 61 72 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a  array, invoke.**
2ed50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f   [sqlite3_reset_
2ed60 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
2ed70 5d 20 70 72 69 6f 72 20 74 6f 20 73 68 75 74 64  ] prior to shutd
2ed80 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20  own to free the 
2ed90 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  memory..**.** {H
2eda0 31 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63  12641} This func
2edb0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 73 20 61  tion registers a
2edc0 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72  n extension entr
2edd0 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 0a  y point that is.
2ede0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f  **          auto
2edf0 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65  matically invoke
2ee00 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77  d whenever a new
2ee10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2ee20 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20  ction].**       
2ee30 20 20 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69     is opened usi
2ee40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ng [sqlite3_open
2ee50 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2ee60 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  en16()],.**     
2ee70 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
2ee80 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  _open_v2()]..**.
2ee90 2a 2a 20 7b 48 31 32 36 34 32 7d 20 44 75 70 6c  ** {H12642} Dupl
2eea0 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73  icate extensions
2eeb0 20 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f   are detected so
2eec0 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   calling this ro
2eed0 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20  utine.**        
2eee0 20 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73    multiple times
2eef0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65   with the same e
2ef00 78 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d  xtension is harm
2ef10 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  less..**.** {H12
2ef20 36 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e  643} This routin
2ef30 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74  e stores a point
2ef40 65 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73  er to the extens
2ef50 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a  ion in an array.
2ef60 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
2ef70 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   is obtained fro
2ef80 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2ef90 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  c()]..**.** {H12
2efa0 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65  644} Automatic e
2efb0 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20  xtensions apply 
2efc0 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61  across all threa
2efd0 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ds..*/.int sqlit
2efe0 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
2eff0 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50  n(void (*xEntryP
2f000 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f  oint)(void));../
2f010 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2f020 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
2f030 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
2f040 20 7b 48 31 32 36 36 30 7d 20 3c 53 32 30 35 30   {H12660} <S2050
2f050 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
2f060 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
2f070 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72  all previously r
2f080 65 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61  egistered automa
2f090 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  tic.** extension
2f0a0 73 2e 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e 64  s. {END}  It und
2f0b0 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
2f0c0 66 20 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b  f all prior.** [
2f0d0 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
2f0e0 65 6e 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e  ension()] calls.
2f0f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d 20  .**.** {H12661} 
2f100 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69  This function di
2f110 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69  sables all previ
2f120 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64  ously registered
2f130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74  .**          aut
2f140 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
2f150 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 32  s..**.** {H12662
2f160 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  } This function 
2f170 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74  disables automat
2f180 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e  ic extensions in
2f190 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f   all threads..*/
2f1a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2f1b0 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
2f1c0 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  on(void);../*.**
2f1d0 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  **** EXPERIMENTA
2f1e0 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63  L - subject to c
2f1f0 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f  hange without no
2f200 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  tice ***********
2f210 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ***.**.** The in
2f220 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76  terface to the v
2f230 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
2f240 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e  hanism is curren
2f250 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
2f260 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
2f270 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
2f280 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
2f290 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
2f2a0 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
2f2b0 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
2f2c0 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
2f2d0 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
2f2e0 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
2f2f0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
2f300 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
2f310 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65  hanism stabilize
2f320 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
2f330 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
2f340 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
2f350 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
2f360 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
2f370 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a  his comment..*/.
2f380 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65  ./*.** Structure
2f390 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69  s used by the vi
2f3a0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65  rtual table inte
2f3b0 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66  rface.*/.typedef
2f3c0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2f3d0 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61  vtab sqlite3_vta
2f3e0 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  b;.typedef struc
2f3f0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
2f400 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64  info sqlite3_ind
2f410 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66  ex_info;.typedef
2f420 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2f430 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69  vtab_cursor sqli
2f440 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b  te3_vtab_cursor;
2f450 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2f460 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73  sqlite3_module s
2f470 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a  qlite3_module;..
2f480 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2f490 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62  Virtual Table Ob
2f4a0 6a 65 63 74 20 7b 48 31 38 30 30 30 7d 20 3c 53  ject {H18000} <S
2f4b0 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  20400>.** KEYWOR
2f4c0 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  DS: sqlite3_modu
2f4d0 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c  le {virtual tabl
2f4e0 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 58 50  e module}.** EXP
2f4f0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
2f500 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20  This structure, 
2f510 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64  sometimes called
2f520 20 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 61   a a "virtual ta
2f530 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a  ble module", .**
2f540 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70   defines the imp
2f550 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
2f560 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
2f570 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72  ].  .** This str
2f580 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20  ucture consists 
2f590 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64  mostly of method
2f5a0 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
2f5b0 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61  ..**.** A virtua
2f5c0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69  l table module i
2f5d0 73 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c  s created by fil
2f5e0 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73  ling in a persis
2f5f0 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  tent.** instance
2f600 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
2f610 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61  re and passing a
2f620 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
2f630 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20   instance.** to 
2f640 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f650 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71  module()] or [sq
2f660 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
2f670 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68  ule_v2()]..** Th
2f680 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72  e registration r
2f690 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74  emains valid unt
2f6a0 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65  il it is replace
2f6b0 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74  d by a different
2f6c0 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e  .** module or un
2f6d0 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73  til the [databas
2f6e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c  e connection] cl
2f6f0 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65  oses.  The conte
2f700 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74  nt.** of this st
2f710 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74  ructure must not
2f720 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74   change while it
2f730 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77   is registered w
2f740 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62  ith.** any datab
2f750 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  ase connection..
2f760 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
2f770 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74  3_module {.  int
2f780 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
2f790 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69   (*xCreate)(sqli
2f7a0 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
2f7b0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2f7c0 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
2f7d0 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
2f7e0 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
2f7f0 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
2f800 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
2f810 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65  ;.  int (*xConne
2f820 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ct)(sqlite3*, vo
2f830 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
2f840 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
2f850 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
2f860 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
2f870 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
2f880 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
2f890 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
2f8a0 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71  (*xBestIndex)(sq
2f8b0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
2f8c0 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  b, sqlite3_index
2f8d0 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28  _info*);.  int (
2f8e0 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71  *xDisconnect)(sq
2f8f0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
2f900 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73  b);.  int (*xDes
2f910 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74  troy)(sqlite3_vt
2f920 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2f930 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
2f940 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
2f950 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2f960 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b  sor **ppCursor);
2f970 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
2f980 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
2f990 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
2f9a0 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33  xFilter)(sqlite3
2f9b0 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69  _vtab_cursor*, i
2f9c0 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74  nt idxNum, const
2f9d0 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20   char *idxStr,. 
2f9e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
2f9f0 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33  nt argc, sqlite3
2fa00 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a  _value **argv);.
2fa10 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73    int (*xNext)(s
2fa20 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2fa30 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45  or*);.  int (*xE
2fa40 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  of)(sqlite3_vtab
2fa50 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
2fa60 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69   (*xColumn)(sqli
2fa70 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
2fa80 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  , sqlite3_contex
2fa90 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  t*, int);.  int 
2faa0 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65  (*xRowid)(sqlite
2fab0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
2fac0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
2fad0 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a  Rowid);.  int (*
2fae0 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33  xUpdate)(sqlite3
2faf0 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71  _vtab *, int, sq
2fb00 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20  lite3_value **, 
2fb10 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29  sqlite3_int64 *)
2fb20 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e  ;.  int (*xBegin
2fb30 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2fb40 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
2fb50 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76  xSync)(sqlite3_v
2fb60 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
2fb70 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71  nt (*xCommit)(sq
2fb80 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
2fb90 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c  b);.  int (*xRol
2fba0 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76  lback)(sqlite3_v
2fbb0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
2fbc0 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69  nt (*xFindFuncti
2fbd0 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  on)(sqlite3_vtab
2fbe0 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72   *pVtab, int nAr
2fbf0 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  g, const char *z
2fc00 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20  Name,.          
2fc10 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2fc20 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c  d (**pxFunc)(sql
2fc30 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2fc40 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2fc50 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  *),.            
2fc60 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
2fc70 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  **ppArg);.  int 
2fc80 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74  (*xRename)(sqlit
2fc90 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
2fca0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77  const char *zNew
2fcb0 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  );.};../*.** CAP
2fcc0 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
2fcd0 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e  able Indexing In
2fce0 66 6f 72 6d 61 74 69 6f 6e 20 7b 48 31 38 31 30  formation {H1810
2fcf0 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b  0} <S20400>.** K
2fd00 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
2fd10 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45  _index_info.** E
2fd20 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
2fd30 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2fd40 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75  dex_info structu
2fd50 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74  re and its subst
2fd60 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64  ructures is used
2fd70 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f   to.** pass info
2fd80 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64  rmation into and
2fd90 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70   receive the rep
2fda0 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65  ly from the [xBe
2fdb0 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68  stIndex].** meth
2fdc0 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c  od of a [virtual
2fdd0 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
2fde0 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65   The fields unde
2fdf0 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65  r **Inputs** are
2fe00 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74   the.** inputs t
2fe10 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64  o xBestIndex and
2fe20 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20   are read-only. 
2fe30 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65   xBestIndex inse
2fe40 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c  rts its.** resul
2fe50 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75  ts into the **Ou
2fe60 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a  tputs** fields..
2fe70 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74  **.** The aConst
2fe80 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65  raint[] array re
2fe90 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75  cords WHERE clau
2fea0 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f  se constraints o
2feb0 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a  f the form:.**.*
2fec0 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f 50  * <pre>column OP
2fed0 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a   expr</pre>.**.*
2fee0 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c  * where OP is =,
2fef0 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67   &lt;, &lt;=, &g
2ff00 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20 54  t;, or &gt;=.  T
2ff10 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70  he particular op
2ff20 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f  erator is.** sto
2ff30 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69  red in aConstrai
2ff40 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e  nt[].op.  The in
2ff50 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
2ff60 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a  n is stored in.*
2ff70 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  * aConstraint[].
2ff80 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74  iColumn.  aConst
2ff90 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69  raint[].usable i
2ffa0 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a  s TRUE if the.**
2ffb0 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67   expr on the rig
2ffc0 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e  ht-hand side can
2ffd0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61   be evaluated (a
2ffe0 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73  nd thus the cons
2fff0 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61  traint.** is usa
30000 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69  ble) and false i
30010 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a  f it cannot..**.
30020 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72  ** The optimizer
30030 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
30040 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20  nverts terms of 
30050 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f  the form "expr O
30060 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64  P column".** and
30070 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d   makes other sim
30080 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20  plifications to 
30090 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65  the WHERE clause
300a0 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74   in an attempt t
300b0 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79  o.** get as many
300c0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
300d0 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72  rms into the for
300e0 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73  m shown above as
300f0 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68   possible..** Th
30100 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
30110 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72  array only repor
30120 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ts WHERE clause 
30130 74 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72  terms in the cor
30140 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61  rect.** form tha
30150 74 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70  t refer to the p
30160 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61  articular virtua
30170 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75  l table being qu
30180 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66  eried..**.** Inf
30190 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
301a0 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
301b0 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  se is stored in 
301c0 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45  aOrderBy[]..** E
301d0 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64  ach term of aOrd
301e0 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63  erBy records a c
301f0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44  olumn of the ORD
30200 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a  ER BY clause..**
30210 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e  .** The [xBestIn
30220 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74  dex] method must
30230 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e   fill aConstrain
30240 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e  tUsage[] with in
30250 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
30260 75 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65  ut what paramete
30270 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46  rs to pass to xF
30280 69 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 49  ilter.  If argvI
30290 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74  ndex>0 then.** t
302a0 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69  he right-hand si
302b0 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73  de of the corres
302c0 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61  ponding aConstra
302d0 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74  int[] is evaluat
302e0 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65  ed.** and become
302f0 73 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d  s the argvIndex-
30300 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76  th entry in argv
30310 2e 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e  .  If aConstrain
30320 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a  tUsage[].omit.**
30330 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74   is true, then t
30340 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  he constraint is
30350 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66   assumed to be f
30360 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20  ully handled by 
30370 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  the.** virtual t
30380 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20  able and is not 
30390 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79  checked again by
303a0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
303b0 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64  he idxNum and id
303c0 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20  xPtr values are 
303d0 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73  recorded and pas
303e0 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  sed into the.** 
303f0 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64  [xFilter] method
30400 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  ..** [sqlite3_fr
30410 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  ee()] is used to
30420 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20   free idxPtr if 
30430 61 6e 64 20 6f 6e 6c 79 20 69 66 66 0a 2a 2a 20  and only iff.** 
30440 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72  needToFreeIdxPtr
30450 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20   is true..**.** 
30460 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  The orderByConsu
30470 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f  med means that o
30480 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c  utput from [xFil
30490 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c  ter]/[xNext] wil
304a0 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68  l occur in.** th
304b0 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20  e correct order 
304c0 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f  to satisfy the O
304d0 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73  RDER BY clause s
304e0 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61  o that no separa
304f0 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74  te.** sorting st
30500 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ep is required..
30510 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61  **.** The estima
30520 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73  tedCost value is
30530 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
30540 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e  the cost of doin
30550 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75  g the.** particu
30560 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66  lar lookup.  A f
30570 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61  ull scan of a ta
30580 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69  ble with N entri
30590 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a  es should have.*
305a0 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20  * a cost of N.  
305b0 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20  A binary search 
305c0 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20  of a table of N 
305d0 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
305e0 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66  ave a.** cost of
305f0 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c   approximately l
30600 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74  og(N)..*/.struct
30610 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
30620 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74  nfo {.  /* Input
30630 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73  s */.  int nCons
30640 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
30650 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65    /* Number of e
30660 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74  ntries in aConst
30670 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63  raint */.  struc
30680 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
30690 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20  constraint {.   
306a0 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
306b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
306c0 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61  olumn on left-ha
306d0 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74  nd side of const
306e0 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e  raint */.     un
306f0 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20  signed char op; 
30700 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74          /* Const
30710 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a  raint operator *
30720 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
30730 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20  char usable;    
30740 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73   /* True if this
30750 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75   constraint is u
30760 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e  sable */.     in
30770 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20  t iTermOffset;  
30780 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
30790 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65  internally - xBe
307a0 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69  stIndex should i
307b0 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43  gnore */.  } *aC
307c0 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
307d0 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f        /* Table o
307e0 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  f WHERE clause c
307f0 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20  onstraints */.  
30800 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20  int nOrderBy;   
30810 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
30820 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
30830 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
30840 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74  ause */.  struct
30850 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f   sqlite3_index_o
30860 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e  rderby {.     in
30870 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
30880 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
30890 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20  n number */.    
308a0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64   unsigned char d
308b0 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  esc;       /* Tr
308c0 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61  ue for DESC.  Fa
308d0 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a  lse for ASC. */.
308e0 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20    } *aOrderBy;  
308f0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
30900 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  The ORDER BY cla
30910 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70  use */.  /* Outp
30920 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  uts */.  struct 
30930 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f  sqlite3_index_co
30940 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b  nstraint_usage {
30950 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64  .    int argvInd
30960 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ex;           /*
30970 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69   if >0, constrai
30980 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72  nt is part of ar
30990 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f  gv to xFilter */
309a0 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68  .    unsigned ch
309b0 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a  ar omit;      /*
309c0 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74   Do not code a t
309d0 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e  est for this con
309e0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a  straint */.  } *
309f0 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
30a00 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20  ;.  int idxNum; 
30a10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
30a20 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f  * Number used to
30a30 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e   identify the in
30a40 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69  dex */.  char *i
30a50 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20  dxStr;          
30a60 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70      /* String, p
30a70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64  ossibly obtained
30a80 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
30a90 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65  lloc */.  int ne
30aa0 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20  edToFreeIdxStr; 
30ab0 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78       /* Free idx
30ac0 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65  Str using sqlite
30ad0 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65  3_free() if true
30ae0 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42   */.  int orderB
30af0 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20  yConsumed;      
30b00 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70   /* True if outp
30b10 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72  ut is already or
30b20 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c  dered */.  doubl
30b30 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b  e estimatedCost;
30b40 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74        /* Estimat
30b50 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67  ed cost of using
30b60 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d   this index */.}
30b70 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
30b80 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
30b90 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e  T_EQ    2.#defin
30ba0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
30bb0 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20  ONSTRAINT_GT    
30bc0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
30bd0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
30be0 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e  T_LE    8.#defin
30bf0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
30c00 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20  ONSTRAINT_LT    
30c10 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
30c20 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
30c30 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66  NT_GE    32.#def
30c40 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
30c50 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43  _CONSTRAINT_MATC
30c60 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  H 64../*.** CAPI
30c70 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
30c80 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
30c90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48  mplementation {H
30ca0 31 38 32 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a  18200} <S20400>.
30cb0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
30cc0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
30cd0 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  ne is used to re
30ce0 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69  gister a new [vi
30cf0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
30d00 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 4d 6f 64  le] name..** Mod
30d10 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62  ule names must b
30d20 65 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66  e registered bef
30d30 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20  ore.** creating 
30d40 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74  a new [virtual t
30d50 61 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20  able] using the 
30d60 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72  module, or befor
30d70 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65  e using a.** pre
30d80 65 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61  existing [virtua
30d90 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65  l table] for the
30da0 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54   module..**.** T
30db0 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69  he module name i
30dc0 73 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20  s registered on 
30dd0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
30de0 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
30df0 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  ied.** by the fi
30e00 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20  rst parameter.  
30e10 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
30e20 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20  module is given 
30e30 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e  by the .** secon
30e40 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
30e50 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
30e60 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
30e70 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  o.** the impleme
30e80 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  ntation of the [
30e90 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
30ea0 64 75 6c 65 5d 2e 20 20 20 54 68 65 20 66 6f 75  dule].   The fou
30eb0 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rth.** parameter
30ec0 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
30ed0 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69   client data poi
30ee0 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73  nter that is pas
30ef0 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69  sed through.** i
30f00 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74 65  nto the [xCreate
30f10 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d  ] and [xConnect]
30f20 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20   methods of the 
30f30 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
30f40 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e  dule.** when a n
30f50 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ew virtual table
30f60 20 69 73 20 62 65 20 62 65 69 6e 67 20 63 72 65   is be being cre
30f70 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69 61  ated or reinitia
30f80 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  lized..**.** Thi
30f90 73 20 69 6e 74 65 72 66 61 63 65 20 68 61 73 20  s interface has 
30fa0 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
30fb0 20 65 66 66 65 63 74 20 61 73 20 63 61 6c 6c 69   effect as calli
30fc0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
30fd0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
30fe0 29 5d 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 63  )] with a NULL c
30ff0 6c 69 65 6e 74 20 64 61 74 61 20 64 65 73 74 72  lient data destr
31000 75 63 74 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45  uctor..*/.SQLITE
31010 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e  _EXPERIMENTAL in
31020 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
31030 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74  _module(.  sqlit
31040 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
31050 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20        /* SQLite 
31060 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65  connection to re
31070 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69  gister module wi
31080 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  th */.  const ch
31090 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20  ar *zName,      
310a0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
310b0 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f  e module */.  co
310c0 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
310d0 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68  le *p,   /* Meth
310e0 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
310f0 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43  le */.  void *pC
31100 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20 20 20  lientData       
31110 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74     /* Client dat
31120 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43  a for xCreate/xC
31130 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  onnect */.);../*
31140 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
31150 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c  gister A Virtual
31160 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74   Table Implement
31170 61 74 69 6f 6e 20 7b 48 31 38 32 31 30 7d 20 3c  ation {H18210} <
31180 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S20400>.** EXPER
31190 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
311a0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64  is routine is id
311b0 65 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 5b  entical to the [
311c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
311d0 6f 64 75 6c 65 28 29 5d 20 6d 65 74 68 6f 64 2c  odule()] method,
311e0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
311f0 69 74 20 68 61 73 20 61 6e 20 65 78 74 72 61 20  it has an extra 
31200 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 70 65  parameter to spe
31210 63 69 66 79 20 0a 2a 2a 20 61 20 64 65 73 74 72  cify .** a destr
31220 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66  uctor function f
31230 6f 72 20 74 68 65 20 63 6c 69 65 6e 74 20 64 61  or the client da
31240 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 53 51 4c  ta pointer.  SQL
31250 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f  ite will.** invo
31260 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
31270 72 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69  r function (if i
31280 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77  t is not NULL) w
31290 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f  hen SQLite.** no
312a0 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68   longer needs th
312b0 65 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f  e pClientData po
312c0 69 6e 74 65 72 2e 20 20 0a 2a 2f 0a 53 51 4c 49  inter.  .*/.SQLI
312d0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
312e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
312f0 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20  te_module_v2(.  
31300 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
31310 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
31320 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  Lite connection 
31330 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75  to register modu
31340 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e  le with */.  con
31350 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
31360 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
31370 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  of the module */
31380 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
31390 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a  _module *p,   /*
313a0 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   Methods for the
313b0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69   module */.  voi
313c0 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20  d *pClientData, 
313d0 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e          /* Clien
313e0 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61  t data for xCrea
313f0 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20  te/xConnect */. 
31400 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
31410 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d  (void*)     /* M
31420 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72  odule destructor
31430 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a   function */.);.
31440 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31450 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
31460 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 7b  nstance Object {
31470 48 31 38 30 31 30 7d 20 3c 53 32 30 34 30 30 3e  H18010} <S20400>
31480 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
31490 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 20 45 58  lite3_vtab.** EX
314a0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
314b0 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20   Every [virtual 
314c0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d  table module] im
314d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
314e0 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20  s a subclass.** 
314f0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
31500 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65   structure to de
31510 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75  scribe a particu
31520 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20  lar instance.** 
31530 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
31540 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75  table].  Each su
31550 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62  bclass will.** b
31560 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68  e tailored to th
31570 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
31580 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
31590 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
315a0 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66  * The purpose of
315b0 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73   this superclass
315c0 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65   is to define ce
315d0 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61  rtain fields tha
315e0 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20  t are.** common 
315f0 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d  to all module im
31600 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a  plementations..*
31610 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62  *.** Virtual tab
31620 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20  les methods can 
31630 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  set an error mes
31640 73 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e  sage by assignin
31650 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62  g a.** string ob
31660 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
31670 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20  ite3_mprintf()] 
31680 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65  to zErrMsg.  The
31690 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a   method should.*
316a0 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74  * take care that
316b0 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e   any prior strin
316c0 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20  g is freed by a 
316d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
316e0 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f  _free()].** prio
316f0 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61  r to assigning a
31700 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a   new string to z
31710 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74  ErrMsg.  After t
31720 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
31730 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64  .** is delivered
31740 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e   up to the clien
31750 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  t application, t
31760 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
31770 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
31780 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69  ** freed by sqli
31790 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74  te3_free() and t
317a0 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64  he zErrMsg field
317b0 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e   will be zeroed.
317c0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
317d0 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73  e3_vtab {.  cons
317e0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
317f0 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54   *pModule;  /* T
31800 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68  he module for th
31810 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  is virtual table
31820 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20   */.  int nRef; 
31830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31840 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47        /* NO LONG
31850 45 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61  ER USED */.  cha
31860 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20  r *zErrMsg;     
31870 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
31880 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72  Error message fr
31890 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  om sqlite3_mprin
318a0 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  tf() */.  /* Vir
318b0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
318c0 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
318d0 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
318e0 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
318f0 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
31900 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
31910 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65  able Cursor Obje
31920 63 74 20 20 7b 48 31 38 30 32 30 7d 20 3c 53 32  ct  {H18020} <S2
31930 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0400>.** KEYWORD
31940 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  S: sqlite3_vtab_
31950 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20  cursor {virtual 
31960 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a  table cursor}.**
31970 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
31980 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75  .** Every [virtu
31990 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
319a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
319b0 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20  uses a subclass 
319c0 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  of the.** follow
319d0 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f  ing structure to
319e0 20 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72   describe cursor
319f0 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74  s that point int
31a00 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61  o the.** [virtua
31a10 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65  l table] and are
31a20 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70   used.** to loop
31a30 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72   through the vir
31a40 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72  tual table.  Cur
31a50 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64  sors are created
31a60 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
31a70 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f  qlite3_module.xO
31a80 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74  pen | xOpen] met
31a90 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  hod of the modul
31aa0 65 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f  e and are destro
31ab0 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73  yed.** by the [s
31ac0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43  qlite3_module.xC
31ad0 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d  lose | xClose] m
31ae0 65 74 68 6f 64 2e 20 20 43 75 73 73 6f 72 73 20  ethod.  Cussors 
31af0 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74  are used.** by t
31b00 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78  he [xFilter], [x
31b10 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b  Next], [xEof], [
31b20 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78  xColumn], and [x
31b30 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a  Rowid] methods.*
31b40 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  * of the module.
31b50 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d    Each module im
31b60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
31b70 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  l define.** the 
31b80 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72  content of a cur
31b90 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f  sor structure to
31ba0 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65   suit its own ne
31bb0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  eds..**.** This 
31bc0 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74  superclass exist
31bd0 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65  s in order to de
31be0 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74  fine fields of t
31bf0 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a  he cursor that.*
31c00 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20  * are common to 
31c10 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  all implementati
31c20 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ons..*/.struct s
31c30 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
31c40 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76  or {.  sqlite3_v
31c50 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20  tab *pVtab;     
31c60 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
31c70 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72  e of this cursor
31c80 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c   */.  /* Virtual
31c90 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
31ca0 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69  ations will typi
31cb0 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69  cally add additi
31cc0 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d  onal fields */.}
31cd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31ce0 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53  F: Declare The S
31cf0 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75  chema Of A Virtu
31d00 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 32 38 30  al Table {H18280
31d10 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58  } <S20400>.** EX
31d20 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
31d30 20 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61   The [xCreate] a
31d40 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65  nd [xConnect] me
31d50 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76  thods of a.** [v
31d60 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
31d70 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69  ule] call this i
31d80 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64  nterface.** to d
31d90 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61  eclare the forma
31da0 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64  t (the names and
31db0 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68   datatypes of th
31dc0 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a  e columns) of.**
31dd0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
31de0 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65  les they impleme
31df0 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  nt..*/.SQLITE_EX
31e00 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73  PERIMENTAL int s
31e10 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76  qlite3_declare_v
31e20 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  tab(sqlite3*, co
31e30 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b  nst char *zSQL);
31e40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31e50 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e  : Overload A Fun
31e60 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74  ction For A Virt
31e70 75 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 33 30  ual Table {H1830
31e80 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45  0} <S20400>.** E
31e90 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
31ea0 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * Virtual tables
31eb0 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74   can provide alt
31ec0 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65  ernative impleme
31ed0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63  ntations of func
31ee0 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74  tions.** using t
31ef0 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f  he [xFindFunctio
31f00 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  n] method of the
31f10 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
31f20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75  module].  .** Bu
31f30 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e  t global version
31f40 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74  s of those funct
31f50 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69  ions.** must exi
31f60 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62  st in order to b
31f70 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a  e overloaded..**
31f80 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b  .** This API mak
31f90 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c  es sure a global
31fa0 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75   version of a fu
31fb0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61  nction with a pa
31fc0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65  rticular.** name
31fd0 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70   and number of p
31fe0 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73  arameters exists
31ff0 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75  .  If no such fu
32000 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a  nction exists.**
32010 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49   before this API
32020 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65   is called, a ne
32030 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72  w function is cr
32040 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c  eated.  The impl
32050 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66  ementation.** of
32060 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f   the new functio
32070 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20  n always causes 
32080 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20  an exception to 
32090 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a  be thrown.  So.*
320a0 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  * the new functi
320b0 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66  on is not good f
320c0 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69  or anything by i
320d0 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79  tself.  Its only
320e0 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74  .** purpose is t
320f0 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64  o be a placehold
32100 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  er function that
32110 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64   can be overload
32120 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 74  ed.** by a [virt
32130 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 53  ual table]..*/.S
32140 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
32150 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  AL int sqlite3_o
32160 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e  verload_function
32170 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
32180 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65   char *zFuncName
32190 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a  , int nArg);../*
321a0 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
321b0 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
321c0 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
321d0 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28   defined above (
321e0 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20  back up.** to a 
321f0 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62  comment remarkab
32200 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68  ly similar to th
32210 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65  is one) is curre
32220 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
32230 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
32240 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
32250 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
32260 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
32270 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
32280 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
32290 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
322a0 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
322b0 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
322c0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
322d0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
322e0 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
322f0 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
32300 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
32310 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
32320 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
32330 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
32340 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a  this comment..**
32350 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45  .****** EXPERIME
32360 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74  NTAL - subject t
32370 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74  o change without
32380 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a   notice ********
32390 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  ******.*/../*.**
323a0 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e   CAPI3REF: A Han
323b0 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42  dle To An Open B
323c0 4c 4f 42 20 7b 48 31 37 38 30 30 7d 20 3c 53 33  LOB {H17800} <S3
323d0 30 32 33 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0230>.** KEYWORD
323e0 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d  S: {BLOB handle}
323f0 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a   {BLOB handles}.
32400 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
32410 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
32420 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
32430 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63  pen BLOB on whic
32440 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  h.** [sqlite3_bl
32450 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
32460 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
32470 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
32480 2e 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20  ..** Objects of 
32490 74 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72  this type are cr
324a0 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
324b0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a  3_blob_open()].*
324c0 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20  * and destroyed 
324d0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
324e0 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68  _close()]..** Th
324f0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
32500 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  read()] and [sql
32510 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
32520 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
32530 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
32540 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d  read or write sm
32550 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20  all subsections 
32560 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20  of the BLOB..** 
32570 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  The [sqlite3_blo
32580 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
32590 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
325a0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f   size of the BLO
325b0 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74  B in bytes..*/.t
325c0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
325d0 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74  lite3_blob sqlit
325e0 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_blob;../*.** 
325f0 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41  CAPI3REF: Open A
32600 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d   BLOB For Increm
32610 65 6e 74 61 6c 20 49 2f 4f 20 7b 48 31 37 38 31  ental I/O {H1781
32620 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a  0} <S30230>.**.*
32630 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
32640 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20  s opens a [BLOB 
32650 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d  handle | handle]
32660 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63   to the BLOB loc
32670 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69  ated.** in row i
32680 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c  Row, column zCol
32690 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c  umn, table zTabl
326a0 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44  e in database zD
326b0 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77  b;.** in other w
326c0 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42  ords, the same B
326d0 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62  LOB that would b
326e0 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a  e selected by:.*
326f0 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
32700 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e    SELECT zColumn
32710 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65   FROM zDb.zTable
32720 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d   WHERE [rowid] =
32730 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   iRow;.** </pre>
32740 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20   {END}.**.** If 
32750 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
32760 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  ter is non-zero,
32770 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69   then the BLOB i
32780 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
32790 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61  d.** and write a
327a0 63 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20  ccess. If it is 
327b0 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69  zero, the BLOB i
327c0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
327d0 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20 49 74 20  d access..** It 
327e0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
327f0 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e  to open a column
32800 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66   that is part of
32810 20 61 6e 20 69 6e 64 65 78 20 6f 72 20 70 72 69   an index or pri
32820 6d 61 72 79 20 0a 2a 2a 20 6b 65 79 20 66 6f 72  mary .** key for
32830 20 77 72 69 74 69 6e 67 2e 20 5e 49 66 20 5b 66   writing. ^If [f
32840 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
32850 72 61 69 6e 74 73 5d 20 61 72 65 20 65 6e 61 62  raints] are enab
32860 6c 65 64 2c 20 69 74 20 69 73 20 0a 2a 2a 20 6e  led, it is .** n
32870 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f  ot possible to o
32880 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61  pen a column tha
32890 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 20 5b  t is part of a [
328a0 63 68 69 6c 64 20 6b 65 79 5d 20 66 6f 72 20 77  child key] for w
328b0 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  riting..**.** No
328c0 74 65 20 74 68 61 74 20 74 68 65 20 64 61 74 61  te that the data
328d0 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74  base name is not
328e0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 68   the filename th
328f0 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  at contains.** t
32900 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 20  he database but 
32910 72 61 74 68 65 72 20 74 68 65 20 73 79 6d 62 6f  rather the symbo
32920 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  lic name of the 
32930 64 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a 2a  database that.**
32940 20 69 73 20 61 73 73 69 67 6e 65 64 20 77 68 65   is assigned whe
32950 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
32960 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e  s connected usin
32970 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 46  g [ATTACH]..** F
32980 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  or the main data
32990 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64  base file, the d
329a0 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20  atabase name is 
329b0 22 6d 61 69 6e 22 2e 0a 2a 2a 20 46 6f 72 20 54  "main"..** For T
329c0 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20  EMP tables, the 
329d0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73  database name is
329e0 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 4f   "temp"..**.** O
329f0 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49  n success, [SQLI
32a00 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
32a10 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b  ed and the new [
32a20 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20  BLOB handle] is 
32a30 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70  written.** to *p
32a40 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65  pBlob. Otherwise
32a50 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
32a60 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
32a70 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a   *ppBlob is set.
32a80 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20  ** to be a null 
32a90 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 69 73  pointer..** This
32aa0 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74   function sets t
32ab0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
32ac0 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63  nection] error c
32ad0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a  ode and message.
32ae0 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  ** accessible vi
32af0 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  a [sqlite3_errco
32b00 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  de()] and [sqlit
32b10 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
32b20 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63   related.** func
32b30 74 69 6f 6e 73 2e 20 20 4e 6f 74 65 20 74 68 61  tions.  Note tha
32b40 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61  t the *ppBlob va
32b50 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73  riable is always
32b60 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20   initialized in 
32b70 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61  a.** way that ma
32b80 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 69  kes it safe to i
32b90 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62  nvoke [sqlite3_b
32ba0 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20  lob_close()] on 
32bb0 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72  *ppBlob.** regar
32bc0 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
32bd0 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20  cess or failure 
32be0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e  of this routine.
32bf0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 6f  .**.** If the ro
32c00 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61  w that a BLOB ha
32c10 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69  ndle points to i
32c20 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e  s modified by an
32c30 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44  .** [UPDATE], [D
32c40 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f  ELETE], or by [O
32c50 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65  N CONFLICT] side
32c60 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e  -effects.** then
32c70 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65   the BLOB handle
32c80 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65   is marked as "e
32c90 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73  xpired"..** This
32ca0 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20   is true if any 
32cb0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f  column of the ro
32cc0 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76  w is changed, ev
32cd0 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f  en a column.** o
32ce0 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e  ther than the on
32cf0 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  e the BLOB handl
32d00 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a 2a  e is open on..**
32d10 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   Calls to [sqlit
32d20 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20  e3_blob_read()] 
32d30 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  and [sqlite3_blo
32d40 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a  b_write()] for.*
32d50 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f 42  * a expired BLOB
32d60 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74   handle fail wit
32d70 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 65  h an return code
32d80 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   of [SQLITE_ABOR
32d90 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 20 77  T]..** Changes w
32da0 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c  ritten into a BL
32db0 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  OB prior to the 
32dc0 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61 72  BLOB expiring ar
32dd0 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63  e not.** rollbac
32de0 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 61 74  k by the expirat
32df0 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e  ion of the BLOB.
32e00 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 20 77    Such changes w
32e10 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a  ill eventually.*
32e20 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20  * commit if the 
32e30 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  transaction cont
32e40 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
32e50 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 73 65 20 74  ion..**.** Use t
32e60 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
32e70 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
32e80 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ace to determine
32e90 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
32ea0 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e  the opened blob.
32eb0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20    The size of a 
32ec0 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20  blob may not be 
32ed0 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a  changed by this.
32ee0 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55  ** interface.  U
32ef0 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20  se the [UPDATE] 
32f00 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63  SQL command to c
32f10 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f  hange the size o
32f20 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a  f a.** blob..**.
32f30 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
32f40 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d  bind_zeroblob()]
32f50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
32f60 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d  sult_zeroblob()]
32f70 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
32f80 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  nd the built-in 
32f90 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66  [zeroblob] SQL f
32fa0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75  unction can be u
32fb0 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c  sed, if desired,
32fc0 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e  .** to create an
32fd0 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c   empty, zero-fil
32fe0 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63  led blob in whic
32ff0 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69  h to read or wri
33000 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73  te using.** this
33010 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
33020 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73  * To avoid a res
33030 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72  ource leak, ever
33040 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e  y open [BLOB han
33050 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e  dle] should even
33060 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c  tually.** be rel
33070 65 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20  eased by a call 
33080 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
33090 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
330a0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
330b0 2a 20 5b 48 31 37 38 31 33 5d 20 5b 48 31 37 38  * [H17813] [H178
330c0 31 34 5d 20 5b 48 31 37 38 31 36 5d 20 5b 48 31  14] [H17816] [H1
330d0 37 38 31 39 5d 20 5b 48 31 37 38 32 31 5d 20 5b  7819] [H17821] [
330e0 48 31 37 38 32 34 5d 0a 2a 2f 0a 69 6e 74 20 73  H17824].*/.int s
330f0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
33100 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
33110 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c  const char *zDb,
33120 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
33130 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63  Table,.  const c
33140 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20  har *zColumn,.  
33150 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52  sqlite3_int64 iR
33160 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c  ow,.  int flags,
33170 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  .  sqlite3_blob 
33180 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a  **ppBlob.);../*.
33190 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
331a0 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65  se A BLOB Handle
331b0 20 7b 48 31 37 38 33 30 7d 20 3c 53 33 30 32 33   {H17830} <S3023
331c0 30 3e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 73 20  0>.**.** Closes 
331d0 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61  an open [BLOB ha
331e0 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f  ndle]..**.** Clo
331f0 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c  sing a BLOB shal
33200 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72  l cause the curr
33210 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ent transaction 
33220 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20  to commit.** if 
33230 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68  there are no oth
33240 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e  er BLOBs, no pen
33250 64 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74  ding prepared st
33260 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68  atements, and th
33270 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
33280 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b  nnection is in [
33290 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d  autocommit mode]
332a0 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 77 72 69 74  ..** If any writ
332b0 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f 20  es were made to 
332c0 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d  the BLOB, they m
332d0 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e 20  ight be held in 
332e0 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74  cache.** until t
332f0 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74 69  he close operati
33300 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c 20  on if they will 
33310 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69  fit..**.** Closi
33320 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65  ng the BLOB ofte
33330 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61  n forces the cha
33340 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64  nges.** out to d
33350 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e  isk and so if an
33360 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63  y I/O errors occ
33370 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69  ur, they will li
33380 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74  kely occur.** at
33390 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74   the time when t
333a0 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65  he BLOB is close
333b0 64 2e 20 20 41 6e 79 20 65 72 72 6f 72 73 20 74  d.  Any errors t
333c0 68 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67  hat occur during
333d0 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20  .** closing are 
333e0 72 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f  reported as a no
333f0 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61  n-zero return va
33400 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 42  lue..**.** The B
33410 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75 6e  LOB is closed un
33420 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20  conditionally.  
33430 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f 75  Even if this rou
33440 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  tine returns.** 
33450 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 74  an error code, t
33460 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c  he BLOB is still
33470 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 43   closed..**.** C
33480 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
33490 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20  ine with a null 
334a0 70 6f 69 6e 74 65 72 20 28 77 68 69 63 68 20 61  pointer (which a
334b0 73 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72  s would be retur
334c0 6e 65 64 0a 2a 2a 20 62 79 20 66 61 69 6c 65 64  ned.** by failed
334d0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
334e0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20  3_blob_open()]) 
334f0 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
33500 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  -op..**.** Requi
33510 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37  rements:.** [H17
33520 38 33 33 5d 20 5b 48 31 37 38 33 36 5d 20 5b 48  833] [H17836] [H
33530 31 37 38 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71  17839].*/.int sq
33540 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
33550 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
33560 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33570 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53 69  F: Return The Si
33580 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c  ze Of An Open BL
33590 4f 42 20 7b 48 31 37 38 34 30 7d 20 3c 53 33 30  OB {H17840} <S30
335a0 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  230>.**.** Retur
335b0 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62  ns the size in b
335c0 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42  ytes of the BLOB
335d0 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20   accessible via 
335e0 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 73 73 66  the .** successf
335f0 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f  ully opened [BLO
33600 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73  B handle] in its
33610 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20   only argument. 
33620 20 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e   The.** incremen
33630 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75  tal blob I/O rou
33640 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72  tines can only r
33650 65 61 64 20 6f 72 20 6f 76 65 72 77 72 69 74 69  ead or overwriti
33660 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62  ng existing.** b
33670 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65  lob content; the
33680 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  y cannot change 
33690 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c  the size of a bl
336a0 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ob..**.** This r
336b0 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b  outine only work
336c0 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e  s on a [BLOB han
336d0 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62  dle] which has b
336e0 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62  een created.** b
336f0 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  y a prior succes
33700 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
33710 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
33720 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73  )] and which has
33730 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f   not.** been clo
33740 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
33750 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20  blob_close()].  
33760 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  Passing any othe
33770 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20  r pointer in.** 
33780 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
33790 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
337a0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
337b0 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  y undesirable be
337c0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 52 65  havior..**.** Re
337d0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
337e0 48 31 37 38 34 33 5d 0a 2a 2f 0a 69 6e 74 20 73  H17843].*/.int s
337f0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
33800 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  s(sqlite3_blob *
33810 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33820 45 46 3a 20 52 65 61 64 20 44 61 74 61 20 46 72  EF: Read Data Fr
33830 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  om A BLOB Increm
33840 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 35 30 7d  entally {H17850}
33850 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20   <S30230>.**.** 
33860 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
33870 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 64 61   used to read da
33880 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20  ta from an open 
33890 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e  [BLOB handle] in
338a0 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73  to a.** caller-s
338b0 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20  upplied buffer. 
338c0 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  N bytes of data 
338d0 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
338e0 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d  buffer Z.** from
338f0 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20   the open BLOB, 
33900 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73  starting at offs
33910 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a  et iOffset..**.*
33920 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66  * If offset iOff
33930 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
33940 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
33950 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
33960 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
33970 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
33980 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
33990 72 65 61 64 2e 20 20 49 66 20 4e 20 6f 72 20 69  read.  If N or i
339a0 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73  Offset is.** les
339b0 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51  s than zero, [SQ
339c0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
339d0 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
339e0 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 20  ata is read..** 
339f0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
33a00 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 65 20  blob (and hence 
33a10 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75  the maximum valu
33a20 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a  e of N+iOffset).
33a30 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
33a40 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ined using the [
33a50 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
33a60 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
33a70 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d 70  .**.** An attemp
33a80 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 61  t to read from a
33a90 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20  n expired [BLOB 
33aa0 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69  handle] fails wi
33ab0 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63  th an.** error c
33ac0 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41  ode of [SQLITE_A
33ad0 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20  BORT]..**.** On 
33ae0 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f  success, SQLITE_
33af0 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  OK is returned..
33b00 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e  ** Otherwise, an
33b10 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
33b20 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72   an [extended er
33b30 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
33b40 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  urned..**.** Thi
33b50 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77  s routine only w
33b60 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20  orks on a [BLOB 
33b70 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61  handle] which ha
33b80 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a  s been created.*
33b90 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63  * by a prior suc
33ba0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
33bb0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
33bc0 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20  en()] and which 
33bd0 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20  has not.** been 
33be0 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  closed by [sqlit
33bf0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
33c00 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f  .  Passing any o
33c10 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a  ther pointer in.
33c20 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ** to this routi
33c30 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ne results in un
33c40 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
33c50 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
33c60 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
33c70 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
33c80 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
33c90 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
33ca0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 35  ments:.** [H1785
33cb0 33 5d 20 5b 48 31 37 38 35 36 5d 20 5b 48 31 37  3] [H17856] [H17
33cc0 38 35 39 5d 20 5b 48 31 37 38 36 32 5d 20 5b 48  859] [H17862] [H
33cd0 31 37 38 36 33 5d 20 5b 48 31 37 38 36 35 5d 20  17863] [H17865] 
33ce0 5b 48 31 37 38 36 38 5d 0a 2a 2f 0a 69 6e 74 20  [H17868].*/.int 
33cf0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
33d00 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  d(sqlite3_blob *
33d10 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e  , void *Z, int N
33d20 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a  , int iOffset);.
33d30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33d40 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f   Write Data Into
33d50 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e   A BLOB Incremen
33d60 74 61 6c 6c 79 20 7b 48 31 37 38 37 30 7d 20 3c  tally {H17870} <
33d70 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30230>.**.** Th
33d80 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
33d90 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74  sed to write dat
33da0 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b  a into an open [
33db0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f  BLOB handle] fro
33dc0 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75  m a.** caller-su
33dd0 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e  pplied buffer. N
33de0 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61   bytes of data a
33df0 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74  re copied from t
33e00 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69  he buffer Z.** i
33e10 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f  nto the open BLO
33e20 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f  B, starting at o
33e30 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a  ffset iOffset..*
33e40 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 42 4c 4f  *.** If the [BLO
33e50 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64  B handle] passed
33e60 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
33e70 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f  gument was not o
33e80 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69  pened for.** wri
33e90 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20  ting (the flags 
33ea0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
33eb0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
33ec0 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a  )] was zero),.**
33ed0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
33ee0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
33ef0 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20  EADONLY]..**.** 
33f00 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
33f10 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68  y only modify th
33f20 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68  e contents of th
33f30 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a 2a  e BLOB; it is.**
33f40 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
33f50 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69   increase the si
33f60 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73 69  ze of a BLOB usi
33f70 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20  ng this API..** 
33f80 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  If offset iOffse
33f90 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e  t is less than N
33fa0 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20   bytes from the 
33fb0 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c  end of the BLOB,
33fc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
33fd0 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
33fe0 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72  nd no data is wr
33ff0 69 74 74 65 6e 2e 20 20 49 66 20 4e 20 69 73 0a  itten.  If N is.
34000 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  ** less than zer
34010 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  o [SQLITE_ERROR]
34020 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
34030 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74   no data is writ
34040 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65  ten..** The size
34050 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 61 6e   of the BLOB (an
34060 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69  d hence the maxi
34070 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69  mum value of N+i
34080 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62  Offset).** can b
34090 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
340a0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
340b0 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e  blob_bytes()] in
340c0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 41  terface..**.** A
340d0 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72 69  n attempt to wri
340e0 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65 64  te to an expired
340f0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66   [BLOB handle] f
34100 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20  ails with an.** 
34110 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53  error code of [S
34120 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20 57  QLITE_ABORT].  W
34130 72 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c 4f  rites to the BLO
34140 42 20 74 68 61 74 20 6f 63 63 75 72 72 65 64 0a  B that occurred.
34150 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 42  ** before the [B
34160 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 69  LOB handle] expi
34170 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c  red are not roll
34180 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a 2a  ed back by the.*
34190 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20  * expiration of 
341a0 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75  the handle, thou
341b0 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 6f  gh of course tho
341c0 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68 74  se changes might
341d0 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f 76  .** have been ov
341e0 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65  erwritten by the
341f0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
34200 65 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f 42  expired the BLOB
34210 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79   handle.** or by
34220 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64 65   other independe
34230 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  nt statements..*
34240 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
34250 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65   SQLITE_OK is re
34260 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72  turned..** Other
34270 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72  wise, an  [error
34280 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78   code] or an [ex
34290 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
342a0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
342b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
342c0 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e  ne only works on
342d0 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d   a [BLOB handle]
342e0 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20   which has been 
342f0 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20  created.** by a 
34300 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
34310 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
34320 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61  3_blob_open()] a
34330 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74  nd which has not
34340 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20  .** been closed 
34350 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
34360 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73  _close()].  Pass
34370 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f  ing any other po
34380 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74  inter in.** to t
34390 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75  his routine resu
343a0 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
343b0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
343c0 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
343d0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  or..**.** See al
343e0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  so: [sqlite3_blo
343f0 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a  b_read()]..**.**
34400 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
34410 2a 20 5b 48 31 37 38 37 33 5d 20 5b 48 31 37 38  * [H17873] [H178
34420 37 34 5d 20 5b 48 31 37 38 37 35 5d 20 5b 48 31  74] [H17875] [H1
34430 37 38 37 36 5d 20 5b 48 31 37 38 37 37 5d 20 5b  7876] [H17877] [
34440 48 31 37 38 37 39 5d 20 5b 48 31 37 38 38 32 5d  H17879] [H17882]
34450 20 5b 48 31 37 38 38 35 5d 0a 2a 2a 20 5b 48 31   [H17885].** [H1
34460 37 38 38 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  7888].*/.int sql
34470 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
34480 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20  sqlite3_blob *, 
34490 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69  const void *z, i
344a0 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65  nt n, int iOffse
344b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
344c0 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69 6c  REF: Virtual Fil
344d0 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73  e System Objects
344e0 20 7b 48 31 31 32 30 30 7d 20 3c 53 32 30 31 30   {H11200} <S2010
344f0 30 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75  0>.**.** A virtu
34500 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56  al filesystem (V
34510 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74  FS) is an [sqlit
34520 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a  e3_vfs] object.*
34530 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73  * that SQLite us
34540 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a  es to interact.*
34550 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72  * with the under
34560 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
34570 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51  system.  Most SQ
34580 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65  Lite builds come
34590 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c   with a.** singl
345a0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68  e default VFS th
345b0 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74  at is appropriat
345c0 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63  e for the host c
345d0 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20  omputer..** New 
345e0 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67  VFSes can be reg
345f0 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73  istered and exis
34600 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62  ting VFSes can b
34610 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a  e unregistered..
34620 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
34630 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
34640 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  provided..**.** 
34650 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  The sqlite3_vfs_
34660 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65  find() interface
34670 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
34680 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65  er to a VFS give
34690 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 4e  n its name..** N
346a0 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73 65  ames are case se
346b0 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 4e 61 6d 65  nsitive..** Name
346c0 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  s are zero-termi
346d0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
346e0 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ngs..** If there
346f0 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20   is no match, a 
34700 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
34710 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20  returned..** If 
34720 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c 4c  zVfsName is NULL
34730 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
34740 74 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65  t VFS is returne
34750 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53  d..**.** New VFS
34760 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65  es are registere
34770 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76  d with sqlite3_v
34780 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a 2a  fs_register()..*
34790 2a 20 45 61 63 68 20 6e 65 77 20 56 46 53 20 62  * Each new VFS b
347a0 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61 75  ecomes the defau
347b0 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d 61  lt VFS if the ma
347c0 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20 73  keDflt flag is s
347d0 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65 20  et..** The same 
347e0 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69 73  VFS can be regis
347f0 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
34800 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a  imes without inj
34810 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20  ury..** To make 
34820 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20  an existing VFS 
34830 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74  into the default
34840 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69   VFS, register i
34850 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20  t again.** with 
34860 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
34870 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64  g set.  If two d
34880 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20 77  ifferent VFSes w
34890 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20  ith the.** same 
348a0 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74 65  name are registe
348b0 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f  red, the behavio
348c0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  r is undefined. 
348d0 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20   If a.** VFS is 
348e0 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
348f0 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e  a name that is N
34900 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20  ULL or an empty 
34910 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20  string,.** then 
34920 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
34930 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
34940 20 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 46   Unregister a VF
34950 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74  S with the sqlit
34960 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
34970 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  r() interface..*
34980 2a 20 49 66 20 74 68 65 20 64 65 66 61 75 6c 74  * If the default
34990 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 73 74   VFS is unregist
349a0 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56 46  ered, another VF
349b0 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a  S is chosen as.*
349c0 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20 20  * the default.  
349d0 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20 74  The choice for t
349e0 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 61 72  he new VFS is ar
349f0 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 52  bitrary..**.** R
34a00 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
34a10 5b 48 31 31 32 30 33 5d 20 5b 48 31 31 32 30 36  [H11203] [H11206
34a20 5d 20 5b 48 31 31 32 30 39 5d 20 5b 48 31 31 32  ] [H11209] [H112
34a30 31 32 5d 20 5b 48 31 31 32 31 35 5d 20 5b 48 31  12] [H11215] [H1
34a40 31 32 31 38 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33  1218].*/.sqlite3
34a50 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66  _vfs *sqlite3_vf
34a60 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61  s_find(const cha
34a70 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e  r *zVfsName);.in
34a80 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  t sqlite3_vfs_re
34a90 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76  gister(sqlite3_v
34aa0 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c  fs*, int makeDfl
34ab0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
34ac0 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73  vfs_unregister(s
34ad0 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f  qlite3_vfs*);../
34ae0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
34af0 75 74 65 78 65 73 20 7b 48 31 37 30 30 30 7d 20  utexes {H17000} 
34b00 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20000>.**.** T
34b10 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
34b20 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ses these routin
34b30 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a  es for thread.**
34b40 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   synchronization
34b50 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20 61 72  . Though they ar
34b60 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69  e intended for i
34b70 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62  nternal.** use b
34b80 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74  y SQLite, code t
34b90 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
34ba0 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70  t SQLite is.** p
34bb0 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20  ermitted to use 
34bc0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
34bd0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
34be0 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
34bf0 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c  ode contains mul
34c00 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
34c10 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73  tions.** of thes
34c20 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
34c30 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74  .  An appropriat
34c40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
34c50 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20  .** is selected 
34c60 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74  automatically at
34c70 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20   compile-time.  
34c80 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a  The following.**
34c90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
34ca0 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69   are available i
34cb0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  n the SQLite cor
34cc0 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
34cd0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
34ce0 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_OS2.** <li>
34cf0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
34d00 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20  PTHREAD.** <li> 
34d10 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57    SQLITE_MUTEX_W
34d20 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  32.** <li>   SQL
34d30 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a  ITE_MUTEX_NOOP.*
34d40 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
34d50 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e  e SQLITE_MUTEX_N
34d60 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  OOP implementati
34d70 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20 72  on is a set of r
34d80 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20  outines.** that 
34d90 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63  does no real loc
34da0 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72  king and is appr
34db0 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20  opriate for use 
34dc0 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74  in.** a single-t
34dd0 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
34de0 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ion.  The SQLITE
34df0 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53  _MUTEX_OS2,.** S
34e00 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52  QLITE_MUTEX_PTHR
34e10 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f  EAD, and SQLITE_
34e20 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d  MUTEX_W32 implem
34e30 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65  entations.** are
34e40 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
34e50 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e   use on OS/2, Un
34e60 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73 2e  ix, and Windows.
34e70 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65  .**.** If SQLite
34e80 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
34e90 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 54  h the SQLITE_MUT
34ea0 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 72 6f  EX_APPDEF prepro
34eb0 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20  cessor.** macro 
34ec0 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 22 2d  defined (with "-
34ed0 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50  DSQLITE_MUTEX_AP
34ee0 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e  PDEF=1"), then n
34ef0 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65  o mutex.** imple
34f00 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e 63  mentation is inc
34f10 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20 6c  luded with the l
34f20 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69 73 20  ibrary. In this 
34f30 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c  case the.** appl
34f40 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
34f50 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d 75 74  ply a custom mut
34f60 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ex implementatio
34f70 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  n using the.** [
34f80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
34f90 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20 74  TEX] option of t
34fa0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
34fb0 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  g() function.** 
34fc0 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 73  before calling s
34fd0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
34fe0 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68 65 72  e() or any other
34ff0 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f   public sqlite3_
35000 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  .** function tha
35010 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  t calls sqlite3_
35020 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
35030 0a 2a 2a 20 7b 48 31 37 30 31 31 7d 20 54 68 65  .** {H17011} The
35040 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
35050 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61  lloc() routine a
35060 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a  llocates a new.*
35070 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75  * mutex and retu
35080 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
35090 20 69 74 2e 20 7b 48 31 37 30 31 32 7d 20 49 66   it. {H17012} If
350a0 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c   it returns NULL
350b0 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74  .** that means t
350c0 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c  hat a mutex coul
350d0 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74  d not be allocat
350e0 65 64 2e 20 7b 48 31 37 30 31 33 7d 20 53 51 4c  ed. {H17013} SQL
350f0 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69  ite.** will unwi
35100 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64  nd its stack and
35110 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
35120 2e 20 7b 48 31 37 30 31 34 7d 20 54 68 65 20 61  . {H17014} The a
35130 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
35140 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
35150 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  c() is one of th
35160 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
35170 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  tants:.**.** <ul
35180 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
35190 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20  E_MUTEX_FAST.** 
351a0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
351b0 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20  EX_RECURSIVE.** 
351c0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
351d0 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
351e0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
351f0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
35200 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  M.** <li>  SQLIT
35210 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
35220 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  EM2.** <li>  SQL
35230 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
35240 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53  _PRNG.** <li>  S
35250 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
35260 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20  IC_LRU.** <li>  
35270 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
35280 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c  TIC_LRU2.** </ul
35290 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 35 7d  >.**.** {H17015}
352a0 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63   The first two c
352b0 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20 73  onstants cause s
352c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
352d0 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a  oc() to create.*
352e0 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20  * a new mutex.  
352f0 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73  The new mutex is
35300 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20   recursive when 
35310 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
35320 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65  URSIVE.** is use
35330 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73  d but not necess
35340 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51  arily so when SQ
35350 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
35360 69 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a  is used. {END}.*
35370 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c  * The mutex impl
35380 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20  ementation does 
35390 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65  not need to make
353a0 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a   a distinction.*
353b0 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
353c0 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
353d0 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
353e0 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f 65  X_FAST if it doe
353f0 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f  s.** not want to
35400 2e 20 20 7b 48 31 37 30 31 36 7d 20 42 75 74 20  .  {H17016} But 
35410 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
35420 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75 72   request a recur
35430 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a  sive mutex in.**
35440 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74 20   cases where it 
35450 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65  really needs one
35460 2e 20 20 7b 45 4e 44 7d 20 49 66 20 61 20 66 61  .  {END} If a fa
35470 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69  ster non-recursi
35480 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  ve mutex.** impl
35490 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 76  ementation is av
354a0 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 68  ailable on the h
354b0 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68  ost platform, th
354c0 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74 65  e mutex subsyste
354d0 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 72  m.** might retur
354e0 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20 69  n such a mutex i
354f0 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 51  n response to SQ
35500 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e  LITE_MUTEX_FAST.
35510 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 37 7d 20  .**.** {H17017} 
35520 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65  The other allowe
35530 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  d parameters to 
35540 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
35550 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74 75 72  loc() each retur
35560 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  n.** a pointer t
35570 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78  o a static preex
35580 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 7b 45  isting mutex. {E
35590 4e 44 7d 20 20 53 69 78 20 73 74 61 74 69 63 20  ND}  Six static 
355a0 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75  mutexes are.** u
355b0 73 65 64 20 62 79 20 74 68 65 20 63 75 72 72 65  sed by the curre
355c0 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  nt version of SQ
355d0 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20 76 65  Lite.  Future ve
355e0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
355f0 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69  .** may add addi
35600 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75  tional static mu
35610 74 65 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d  texes.  Static m
35620 75 74 65 78 65 73 20 61 72 65 20 66 6f 72 20 69  utexes are for i
35630 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62  nternal.** use b
35640 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20  y SQLite only.  
35650 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
35660 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74  t use SQLite mut
35670 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75  exes should.** u
35680 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61  se only the dyna
35690 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65 74 75  mic mutexes retu
356a0 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d  rned by SQLITE_M
356b0 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20  UTEX_FAST or.** 
356c0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
356d0 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48  URSIVE..**.** {H
356e0 31 37 30 31 38 7d 20 4e 6f 74 65 20 74 68 61 74  17018} Note that
356f0 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64   if one of the d
35700 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72  ynamic mutex par
35710 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f  ameters (SQLITE_
35720 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72  MUTEX_FAST.** or
35730 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
35740 43 55 52 53 49 56 45 29 20 69 73 20 75 73 65 64  CURSIVE) is used
35750 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75   then sqlite3_mu
35760 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72  tex_alloc().** r
35770 65 74 75 72 6e 73 20 61 20 64 69 66 66 65 72 65  eturns a differe
35780 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72  nt mutex on ever
35790 79 20 63 61 6c 6c 2e 20 20 7b 48 31 37 30 33 34  y call.  {H17034
357a0 7d 20 42 75 74 20 66 6f 72 20 74 68 65 20 73 74  } But for the st
357b0 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 74 79  atic.** mutex ty
357c0 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20 6d 75  pes, the same mu
357d0 74 65 78 20 69 73 20 72 65 74 75 72 6e 65 64 20  tex is returned 
357e0 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20 74 68  on every call th
357f0 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20 73 61  at has.** the sa
35800 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a  me type number..
35810 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 39 7d 20 54  **.** {H17019} T
35820 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
35830 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
35840 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72  deallocates a pr
35850 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f  eviously.** allo
35860 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75  cated dynamic mu
35870 74 65 78 2e 20 7b 48 31 37 30 32 30 7d 20 53 51  tex. {H17020} SQ
35880 4c 69 74 65 20 69 73 20 63 61 72 65 66 75 6c 20  Lite is careful 
35890 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 65 76  to deallocate ev
358a0 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  ery.** dynamic m
358b0 75 74 65 78 20 74 68 61 74 20 69 74 20 61 6c 6c  utex that it all
358c0 6f 63 61 74 65 73 2e 20 7b 41 31 37 30 32 31 7d  ocates. {A17021}
358d0 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74   The dynamic mut
358e0 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65  exes must not be
358f0 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20   in.** use when 
35900 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63  they are dealloc
35910 61 74 65 64 2e 20 7b 41 31 37 30 32 32 7d 20 41  ated. {A17022} A
35920 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 65 61  ttempting to dea
35930 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74 69 63  llocate a static
35940 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75 6c 74  .** mutex result
35950 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
35960 65 68 61 76 69 6f 72 2e 20 7b 48 31 37 30 32 33  ehavior. {H17023
35970 7d 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64  } SQLite never d
35980 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20  eallocates.** a 
35990 73 74 61 74 69 63 20 6d 75 74 65 78 2e 20 7b 45  static mutex. {E
359a0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ND}.**.** The sq
359b0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
359c0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
359d0 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74  mutex_try() rout
359e0 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ines attempt.** 
359f0 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78  to enter a mutex
35a00 2e 20 7b 48 31 37 30 32 34 7d 20 49 66 20 61 6e  . {H17024} If an
35a10 6f 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20  other thread is 
35a20 61 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20 74  already within t
35a30 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c  he mutex,.** sql
35a40 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
35a50 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e  () will block an
35a60 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
35a70 74 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72  try() will retur
35a80 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59  n.** SQLITE_BUSY
35a90 2e 20 7b 48 31 37 30 32 35 7d 20 20 54 68 65 20  . {H17025}  The 
35aa0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
35ab0 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  y() interface re
35ac0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
35ad0 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73  ].** upon succes
35ae0 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 7b 48 31  sful entry.  {H1
35af0 37 30 32 36 7d 20 4d 75 74 65 78 65 73 20 63 72  7026} Mutexes cr
35b00 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53  eated using.** S
35b10 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
35b20 52 53 49 56 45 20 63 61 6e 20 62 65 20 65 6e 74  RSIVE can be ent
35b30 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
35b40 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d 65 20  mes by the same 
35b50 74 68 72 65 61 64 2e 0a 2a 2a 20 7b 48 31 37 30  thread..** {H170
35b60 32 37 7d 20 49 6e 20 73 75 63 68 20 63 61 73 65  27} In such case
35b70 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20  s the,.** mutex 
35b80 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20 61  must be exited a
35b90 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f  n equal number o
35ba0 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61  f times before a
35bb0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
35bc0 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 7b 41 31   can enter.  {A1
35bd0 37 30 32 38 7d 20 49 66 20 74 68 65 20 73 61 6d  7028} If the sam
35be0 65 20 74 68 72 65 61 64 20 74 72 69 65 73 20 74  e thread tries t
35bf0 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65  o enter any othe
35c00 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74  r.** kind of mut
35c10 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ex more than onc
35c20 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  e, the behavior 
35c30 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
35c40 20 7b 48 31 37 30 32 39 7d 20 53 51 4c 69 74 65   {H17029} SQLite
35c50 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69   will never exhi
35c60 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61  bit.** such beha
35c70 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20  vior in its own 
35c80 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 0a  use of mutexes..
35c90 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79 73 74 65  **.** Some syste
35ca0 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ms (for example,
35cb0 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64 6f 20   Windows 95) do 
35cc0 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65 20  not support the 
35cd0 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70  operation.** imp
35ce0 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71 6c 69  lemented by sqli
35cf0 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2e  te3_mutex_try().
35d00 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73 74 65    On those syste
35d10 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  ms, sqlite3_mute
35d20 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c 6c 20  x_try().** will 
35d30 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 53 51  always return SQ
35d40 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b 48 31 37  LITE_BUSY.  {H17
35d50 30 33 30 7d 20 54 68 65 20 53 51 4c 69 74 65 20  030} The SQLite 
35d60 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75  core only ever u
35d70 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ses.** sqlite3_m
35d80 75 74 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e  utex_try() as an
35d90 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f   optimization so
35da0 20 74 68 69 73 20 69 73 20 61 63 63 65 70 74 61   this is accepta
35db0 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ble behavior..**
35dc0 0a 2a 2a 20 7b 48 31 37 30 33 31 7d 20 54 68 65  .** {H17031} The
35dd0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c   sqlite3_mutex_l
35de0 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20 65  eave() routine e
35df0 78 69 74 73 20 61 20 6d 75 74 65 78 20 74 68 61  xits a mutex tha
35e00 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  t was.** previou
35e10 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74  sly entered by t
35e20 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20  he same thread. 
35e30 20 7b 41 31 37 30 33 32 7d 20 54 68 65 20 62 65   {A17032} The be
35e40 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
35e50 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d 75  efined if the mu
35e60 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72 65  tex is not curre
35e70 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20  ntly entered by 
35e80 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74  the.** calling t
35e90 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 20  hread or is not 
35ea0 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61  currently alloca
35eb0 74 65 64 2e 20 20 7b 48 31 37 30 33 33 7d 20 53  ted.  {H17033} S
35ec0 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65  QLite will.** ne
35ed0 76 65 72 20 64 6f 20 65 69 74 68 65 72 2e 20 7b  ver do either. {
35ee0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  END}.**.** If th
35ef0 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  e argument to sq
35f00 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
35f10 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74  r(), sqlite3_mut
35f20 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a 2a 20  ex_try(), or.** 
35f30 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
35f40 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  ave() is a NULL 
35f50 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 61 6c  pointer, then al
35f60 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  l three routines
35f70 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20 6e 6f  .** behave as no
35f80 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  -ops..**.** See 
35f90 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d  also: [sqlite3_m
35fa0 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64  utex_held()] and
35fb0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
35fc0 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73  notheld()]..*/.s
35fd0 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71  qlite3_mutex *sq
35fe0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
35ff0 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  c(int);.void sql
36000 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28  ite3_mutex_free(
36010 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
36020 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75  .void sqlite3_mu
36030 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 65  tex_enter(sqlite
36040 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73  3_mutex*);.int s
36050 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
36060 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
36070 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d  ;.void sqlite3_m
36080 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74  utex_leave(sqlit
36090 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a  e3_mutex*);../*.
360a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
360b0 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  ex Methods Objec
360c0 74 20 7b 48 31 37 31 32 30 7d 20 3c 53 32 30 31  t {H17120} <S201
360d0 33 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  30>.** EXPERIMEN
360e0 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  TAL.**.** An ins
360f0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74  tance of this st
36100 72 75 63 74 75 72 65 20 64 65 66 69 6e 65 73 20  ructure defines 
36110 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f  the low-level ro
36120 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74  utines.** used t
36130 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20 75  o allocate and u
36140 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a  se mutexes..**.*
36150 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68 65 20 64  * Usually, the d
36160 65 66 61 75 6c 74 20 6d 75 74 65 78 20 69 6d 70  efault mutex imp
36170 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72 6f  lementations pro
36180 76 69 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  vided by SQLite 
36190 61 72 65 0a 2a 2a 20 73 75 66 66 69 63 69 65 6e  are.** sufficien
361a0 74 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 75  t, however the u
361b0 73 65 72 20 68 61 73 20 74 68 65 20 6f 70 74 69  ser has the opti
361c0 6f 6e 20 6f 66 20 73 75 62 73 74 69 74 75 74 69  on of substituti
361d0 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20 69  ng a custom.** i
361e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
361f0 72 20 73 70 65 63 69 61 6c 69 7a 65 64 20 64 65  r specialized de
36200 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79 73  ployments or sys
36210 74 65 6d 73 20 66 6f 72 20 77 68 69 63 68 20 53  tems for which S
36220 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  QLite.** does no
36230 74 20 70 72 6f 76 69 64 65 20 61 20 73 75 69 74  t provide a suit
36240 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
36250 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63 61 73  ion. In this cas
36260 65 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 63  e, the user.** c
36270 72 65 61 74 65 73 20 61 6e 64 20 70 6f 70 75 6c  reates and popul
36280 61 74 65 73 20 61 6e 20 69 6e 73 74 61 6e 63 65  ates an instance
36290 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
362a0 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74 6f  re to pass.** to
362b0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
362c0 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 74 68 65  ) along with the
362d0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
362e0 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a  MUTEX] option..*
362f0 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20  * Additionally, 
36300 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
36310 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63 61  his structure ca
36320 6e 20 62 65 20 75 73 65 64 20 61 73 20 61 6e 0a  n be used as an.
36330 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 69 61 62  ** output variab
36340 6c 65 20 77 68 65 6e 20 71 75 65 72 79 69 6e 67  le when querying
36350 20 74 68 65 20 73 79 73 74 65 6d 20 66 6f 72 20   the system for 
36360 74 68 65 20 63 75 72 72 65 6e 74 20 6d 75 74 65  the current mute
36370 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  x.** implementat
36380 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65 20 5b  ion, using the [
36390 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
363a0 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a  TMUTEX] option..
363b0 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78  **.** The xMutex
363c0 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 65 66 69  Init method defi
363d0 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75  ned by this stru
363e0 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64  cture is invoked
363f0 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73   as.** part of s
36400 79 73 74 65 6d 20 69 6e 69 74 69 61 6c 69 7a 61  ystem initializa
36410 74 69 6f 6e 20 62 79 20 74 68 65 20 73 71 6c 69  tion by the sqli
36420 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
36430 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 7b 48   function..** {H
36440 31 37 30 30 31 7d 20 54 68 65 20 78 4d 75 74 65  17001} The xMute
36450 78 49 6e 69 74 20 72 6f 75 74 69 6e 65 20 73 68  xInit routine sh
36460 61 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 79  all be called by
36470 20 53 51 4c 69 74 65 20 6f 6e 63 65 20 66 6f 72   SQLite once for
36480 20 65 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69   each.** effecti
36490 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ve call to [sqli
364a0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
364b0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75  ]..**.** The xMu
364c0 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65  texEnd method de
364d0 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74  fined by this st
364e0 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b  ructure is invok
364f0 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  ed as.** part of
36500 20 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e   system shutdown
36510 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
36520 73 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74  shutdown() funct
36530 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c  ion. The.** impl
36540 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
36550 69 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70  is method is exp
36560 65 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65  ected to release
36570 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67   all outstanding
36580 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62  .** resources ob
36590 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75  tained by the mu
365a0 74 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c  tex methods impl
365b0 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65  ementation, espe
365c0 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20  cially.** those 
365d0 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20  obtained by the 
365e0 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f  xMutexInit metho
365f0 64 2e 20 7b 48 31 37 30 30 33 7d 20 54 68 65 20  d. {H17003} The 
36600 78 4d 75 74 65 78 45 6e 64 28 29 0a 2a 2a 20 69  xMutexEnd().** i
36610 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62  nterface shall b
36620 65 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66  e invoked once f
36630 6f 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20  or each call to 
36640 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
36650 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  n()]..**.** The 
36660 72 65 6d 61 69 6e 69 6e 67 20 73 65 76 65 6e 20  remaining seven 
36670 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 20  methods defined 
36680 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72  by this structur
36690 65 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a  e (xMutexAlloc,.
366a0 2a 2a 20 78 4d 75 74 65 78 46 72 65 65 2c 20 78  ** xMutexFree, x
366b0 4d 75 74 65 78 45 6e 74 65 72 2c 20 78 4d 75 74  MutexEnter, xMut
366c0 65 78 54 72 79 2c 20 78 4d 75 74 65 78 4c 65 61  exTry, xMutexLea
366d0 76 65 2c 20 78 4d 75 74 65 78 48 65 6c 64 20 61  ve, xMutexHeld a
366e0 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f 74 68  nd.** xMutexNoth
366f0 65 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74 20 74  eld) implement t
36700 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74  he following int
36710 65 72 66 61 63 65 73 20 28 72 65 73 70 65 63 74  erfaces (respect
36720 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ively):.**.** <u
36730 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  l>.**   <li>  [s
36740 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
36750 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  oc()] </li>.**  
36760 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
36770 6d 75 74 65 78 5f 66 72 65 65 28 29 5d 20 3c 2f  mutex_free()] </
36780 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
36790 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
367a0 74 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  ter()] </li>.** 
367b0 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
367c0 5f 6d 75 74 65 78 5f 74 72 79 28 29 5d 20 3c 2f  _mutex_try()] </
367d0 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
367e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
367f0 61 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  ave()] </li>.** 
36800 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
36810 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 3c  _mutex_held()] <
36820 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
36830 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e  [sqlite3_mutex_n
36840 6f 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a  otheld()] </li>.
36850 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
36860 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
36870 63 65 20 69 73 20 74 68 61 74 20 74 68 65 20 70  ce is that the p
36880 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58  ublic sqlite3_XX
36890 58 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d  X functions enum
368a0 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20  erated.** above 
368b0 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
368c0 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  any invocations 
368d0 74 68 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c  that pass a NULL
368e0 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
368f0 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d  .** of a valid m
36900 75 74 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65  utex handle. The
36910 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
36920 20 6f 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20   of the methods 
36930 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  defined.** by th
36940 69 73 20 73 74 72 75 63 74 75 72 65 20 61 72 65  is structure are
36950 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f   not required to
36960 20 68 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73   handle this cas
36970 65 2c 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a  e, the results.*
36980 2a 20 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e  * of passing a N
36990 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  ULL pointer inst
369a0 65 61 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d  ead of a valid m
369b0 75 74 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20  utex handle are 
369c0 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e  undefined.** (i.
369d0 65 2e 20 69 74 20 69 73 20 61 63 63 65 70 74 61  e. it is accepta
369e0 62 6c 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61  ble to provide a
369f0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
36a00 20 74 68 61 74 20 73 65 67 66 61 75 6c 74 73 20   that segfaults 
36a10 69 66 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73  if.** it is pass
36a20 65 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ed a NULL pointe
36a30 72 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  r)..**.** The xM
36a40 75 74 65 78 49 6e 69 74 28 29 20 6d 65 74 68 6f  utexInit() metho
36a50 64 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  d must be thread
36a60 73 61 66 65 2e 20 20 49 74 20 6d 75 73 74 20 62  safe.  It must b
36a70 65 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a  e harmless to.**
36a80 20 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e   invoke xMutexIn
36a90 69 74 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d  it() mutiple tim
36aa0 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
36ab0 6d 65 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77  me process and w
36ac0 69 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76  ithout.** interv
36ad0 65 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78  ening calls to x
36ae0 4d 75 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63  MutexEnd().  Sec
36af0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
36b00 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78  nt calls to.** x
36b10 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74  MutexInit() must
36b20 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   be no-ops..**.*
36b30 2a 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d  * xMutexInit() m
36b40 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69  ust not use SQLi
36b50 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  te memory alloca
36b60 74 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d  tion ([sqlite3_m
36b70 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20  alloc()].** and 
36b80 69 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e  its associates).
36b90 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75    Similarly, xMu
36ba0 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20  texAlloc() must 
36bb0 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d  not use SQLite m
36bc0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
36bd0 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69 63  ion for a static
36be0 20 6d 75 74 65 78 2e 20 20 48 6f 77 65 76 65 72   mutex.  However
36bf0 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d   xMutexAlloc() m
36c00 61 79 20 75 73 65 20 53 51 4c 69 74 65 0a 2a 2a  ay use SQLite.**
36c10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
36c20 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 20 6f 72  on for a fast or
36c30 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
36c40 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
36c50 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 78  ill invoke the x
36c60 4d 75 74 65 78 45 6e 64 28 29 20 6d 65 74 68 6f  MutexEnd() metho
36c70 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
36c80 73 68 75 74 64 6f 77 6e 28 29 5d 20 69 73 0a 2a  shutdown()] is.*
36c90 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74 20 6f 6e  * called, but on
36ca0 6c 79 20 69 66 20 74 68 65 20 70 72 69 6f 72 20  ly if the prior 
36cb0 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78 49 6e  call to xMutexIn
36cc0 69 74 20 72 65 74 75 72 6e 65 64 20 53 51 4c 49  it returned SQLI
36cd0 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d 75  TE_OK..** If xMu
36ce0 74 65 78 49 6e 69 74 20 66 61 69 6c 73 20 69 6e  texInit fails in
36cf0 20 61 6e 79 20 77 61 79 2c 20 69 74 20 69 73 20   any way, it is 
36d00 65 78 70 65 63 74 65 64 20 74 6f 20 63 6c 65 61  expected to clea
36d10 6e 20 75 70 20 61 66 74 65 72 20 69 74 73 65 6c  n up after itsel
36d20 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 72 65  f.** prior to re
36d30 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70 65  turning..*/.type
36d40 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
36d50 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
36d60 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
36d70 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
36d80 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
36d90 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78  hods {.  int (*x
36da0 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29  MutexInit)(void)
36db0 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78  ;.  int (*xMutex
36dc0 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71  End)(void);.  sq
36dd0 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78  lite3_mutex *(*x
36de0 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29  MutexAlloc)(int)
36df0 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65  ;.  void (*xMute
36e00 78 46 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d  xFree)(sqlite3_m
36e10 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20  utex *);.  void 
36e20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73  (*xMutexEnter)(s
36e30 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
36e40 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54  .  int (*xMutexT
36e50 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ry)(sqlite3_mute
36e60 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  x *);.  void (*x
36e70 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69  MutexLeave)(sqli
36e80 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20  te3_mutex *);.  
36e90 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64  int (*xMutexHeld
36ea0 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  )(sqlite3_mutex 
36eb0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  *);.  int (*xMut
36ec0 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74  exNotheld)(sqlit
36ed0 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a  e3_mutex *);.};.
36ee0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36ef0 20 4d 75 74 65 78 20 56 65 72 69 66 69 63 61 74   Mutex Verificat
36f00 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31  ion Routines {H1
36f10 37 30 38 30 7d 20 3c 53 32 30 31 33 30 3e 20 3c  7080} <S20130> <
36f20 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30800>.**.** Th
36f30 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
36f40 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74  held() and sqlit
36f50 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
36f60 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  () routines.** a
36f70 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
36f80 75 73 65 20 69 6e 73 69 64 65 20 61 73 73 65 72  use inside asser
36f90 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  t() statements. 
36fa0 7b 48 31 37 30 38 31 7d 20 54 68 65 20 53 51 4c  {H17081} The SQL
36fb0 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65  ite core.** neve
36fc0 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75  r uses these rou
36fd0 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73  tines except ins
36fe0 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20  ide an assert() 
36ff0 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  and applications
37000 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20  .** are advised 
37010 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65  to follow the le
37020 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20  ad of the core. 
37030 20 7b 48 31 37 30 38 32 7d 20 54 68 65 20 63 6f   {H17082} The co
37040 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69  re only.** provi
37050 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  des implementati
37060 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f  ons for these ro
37070 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69  utines when it i
37080 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
37090 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45  th the SQLITE_DE
370a0 42 55 47 20 66 6c 61 67 2e 20 20 7b 41 31 37 30  BUG flag.  {A170
370b0 38 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75 74  87} External mut
370c0 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ex implementatio
370d0 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72  ns.** are only r
370e0 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69  equired to provi
370f0 64 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  de these routine
37100 73 20 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55  s if SQLITE_DEBU
37110 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20  G is.** defined 
37120 61 6e 64 20 69 66 20 4e 44 45 42 55 47 20 69 73  and if NDEBUG is
37130 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a   not defined..**
37140 0a 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54 68 65  .** {H17083} The
37150 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  se routines shou
37160 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69  ld return true i
37170 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74  f the mutex in t
37180 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  heir argument.**
37190 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20   is held or not 
371a0 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65  held, respective
371b0 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69  ly, by the calli
371c0 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a  ng thread..**.**
371d0 20 7b 58 31 37 30 38 34 7d 20 54 68 65 20 69 6d   {X17084} The im
371e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
371f0 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20  not required to 
37200 70 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e  provided version
37210 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f  s of these.** ro
37220 75 74 69 6e 65 73 20 74 68 61 74 20 61 63 74 75  utines that actu
37230 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74 68  ally work. If th
37240 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
37250 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64   does not provid
37260 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72  e working.** ver
37270 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72  sions of these r
37280 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75  outines, it shou
37290 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76  ld at least prov
372a0 69 64 65 20 73 74 75 62 73 20 74 68 61 74 20 61  ide stubs that a
372b0 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20  lways.** return 
372c0 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65  true so that one
372d0 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70   does not get sp
372e0 75 72 69 6f 75 73 20 61 73 73 65 72 74 69 6f 6e  urious assertion
372f0 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a   failures..**.**
37300 20 7b 48 31 37 30 38 35 7d 20 49 66 20 74 68 65   {H17085} If the
37310 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
37320 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
37330 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
37340 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ter then.** the 
37350 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72  routine should r
37360 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20  eturn 1.  {END} 
37370 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74  This seems count
37380 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e  er-intuitive sin
37390 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68  ce.** clearly th
373a0 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62  e mutex cannot b
373b0 65 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65  e held if it doe
373c0 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75  s not exist.  Bu
373d0 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61  t the.** the rea
373e0 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f  son the mutex do
373f0 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20  es not exist is 
37400 62 65 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  because the buil
37410 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e  d is not.** usin
37420 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20  g mutexes.  And 
37430 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74  we do not want t
37440 68 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74  he assert() cont
37450 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61  aining the.** ca
37460 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  ll to sqlite3_mu
37470 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61  tex_held() to fa
37480 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72  il, so a non-zer
37490 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74  o return is.** t
374a0 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 74  he appropriate t
374b0 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 48 31  hing to do.  {H1
374c0 37 30 38 36 7d 20 54 68 65 20 73 71 6c 69 74 65  7086} The sqlite
374d0 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
374e0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73  ).** interface s
374f0 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72  hould also retur
37500 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61  n 1 when given a
37510 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
37520 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75  /.int sqlite3_mu
37530 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33  tex_held(sqlite3
37540 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71  _mutex*);.int sq
37550 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
37560 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  eld(sqlite3_mute
37570 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x*);../*.** CAPI
37580 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70 65  3REF: Mutex Type
37590 73 20 7b 48 31 37 30 30 31 7d 20 3c 48 31 37 30  s {H17001} <H170
375a0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  00>.**.** The [s
375b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
375c0 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  oc()] interface 
375d0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
375e0 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68  rgument.** which
375f0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   is one of these
37600 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
37610 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ts..**.** The se
37620 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75 74 65  t of static mute
37630 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65 20 66  xes may change f
37640 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65 20 72  rom one SQLite r
37650 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a 2a 2a  elease to the.**
37660 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
37670 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 72 69  ions that overri
37680 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  de the built-in 
37690 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75 73 74  mutex logic must
376a0 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20   be.** prepared 
376b0 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20 61  to accommodate a
376c0 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63  dditional static
376d0 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 65   mutexes..*/.#de
376e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
376f0 58 5f 46 41 53 54 20 20 20 20 20 20 20 20 20 20  X_FAST          
37700 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
37710 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
37720 49 56 45 20 20 20 20 20 20 20 20 31 0a 23 64 65  IVE        1.#de
37730 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
37740 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 20  X_STATIC_MASTER 
37750 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
37760 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
37770 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f 2a  _MEM       3  /*
37780 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
37790 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
377a0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
377b0 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f 2a  _MEM2      4  /*
377c0 20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23 64 65   NOT USED */.#de
377d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
377e0 58 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20 20 20  X_STATIC_OPEN   
377f0 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
37800 42 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f 0a 23  BtreeOpen() */.#
37810 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
37820 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 20  TEX_STATIC_PRNG 
37830 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
37840 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23  e3_random() */.#
37850 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
37860 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 20  TEX_STATIC_LRU  
37870 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70       6  /* lru p
37880 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66  age list */.#def
37890 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
378a0 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20 20 20  _STATIC_LRU2    
378b0 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61 67 65    7  /* lru page
378c0 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   list */../*.** 
378d0 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
378e0 76 65 20 74 68 65 20 6d 75 74 65 78 20 66 6f 72  ve the mutex for
378f0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
37900 65 63 74 69 6f 6e 20 7b 48 31 37 30 30 32 7d 20  ection {H17002} 
37910 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H17000>.**.** T
37920 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
37930 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
37940 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
37950 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ex] object that 
37960 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 20 61  .** serializes a
37970 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b 64 61  ccess to the [da
37980 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37990 6e 5d 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  n] given in the 
379a0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e  argument.** when
379b0 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
379c0 6d 6f 64 65 5d 20 69 73 20 53 65 72 69 61 6c 69  mode] is Seriali
379d0 7a 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  zed..** If the [
379e0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
379f0 69 73 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  is Single-thread
37a00 20 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   or Multi-thread
37a10 20 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f   then this.** ro
37a20 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
37a30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
37a40 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  .sqlite3_mutex *
37a50 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
37a60 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
37a70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 77  ** CAPI3REF: Low
37a80 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f  -Level Control O
37a90 66 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73  f Database Files
37aa0 20 7b 48 31 31 33 30 30 7d 20 3c 53 33 30 38 30   {H11300} <S3080
37ab0 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31  0>.**.** {H11301
37ac0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  } The [sqlite3_f
37ad0 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
37ae0 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
37af0 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20   direct call to 
37b00 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74  the.** xFileCont
37b10 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74  rol method for t
37b20 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
37b30 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61  ethods] object a
37b40 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
37b50 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
37b60 61 74 61 62 61 73 65 20 69 64 65 6e 74 69 66 69  atabase identifi
37b70 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
37b80 20 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33   argument. {H113
37b90 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20  02} The.** name 
37ba0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
37bb0 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  is the name assi
37bc0 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74 61  gned to the data
37bd0 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c  base by the.** <
37be0 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74  a href="lang_att
37bf0 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48  ach.html">ATTACH
37c00 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64  </a> SQL command
37c10 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65   that opened the
37c20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b 48  .** database. {H
37c30 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f  11303} To contro
37c40 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  l the main datab
37c50 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74 68  ase file, use th
37c60 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a  e name "main".**
37c70 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
37c80 65 72 2e 20 7b 48 31 31 33 30 34 7d 20 54 68 65  er. {H11304} The
37c90 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
37ca0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
37cb0 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
37cc0 61 72 65 20 70 61 73 73 65 64 20 64 69 72 65 63  are passed direc
37cd0 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74  tly through to t
37ce0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
37cf0 69 72 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f  ird parameters o
37d00 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f  f.** the xFileCo
37d10 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b  ntrol method.  {
37d20 48 31 31 33 30 35 7d 20 54 68 65 20 72 65 74 75  H11305} The retu
37d30 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
37d40 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20  xFileControl.** 
37d50 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 74  method becomes t
37d60 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
37d70 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e  of this routine.
37d80 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20  .**.** {H11306} 
37d90 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
37da0 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d 65  rameter (zDbName
37db0 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  ) does not match
37dc0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79   the name of any
37dd0 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73  .** open databas
37de0 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c  e file, then SQL
37df0 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65 74  ITE_ERROR is ret
37e00 75 72 6e 65 64 2e 20 7b 48 31 31 33 30 37 7d 20  urned. {H11307} 
37e10 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f  This error.** co
37e20 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62  de is not rememb
37e30 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f  ered and will no
37e40 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79  t be recalled by
37e50 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
37e60 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  e()].** or [sqli
37e70 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b  te3_errmsg()]. {
37e80 41 31 31 33 30 38 7d 20 54 68 65 20 75 6e 64 65  A11308} The unde
37e90 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74  rlying xFileCont
37ea0 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68 74  rol method might
37eb0 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  .** also return 
37ec0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b  SQLITE_ERROR.  {
37ed0 41 31 31 33 30 39 7d 20 54 68 65 72 65 20 69 73  A11309} There is
37ee0 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74 69   no way to disti
37ef0 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a 2a  nguish between.*
37f00 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a  * an incorrect z
37f10 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53 51  DbName and an SQ
37f20 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75 72  LITE_ERROR retur
37f30 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 72  n from the under
37f40 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f  lying.** xFileCo
37f50 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45  ntrol method. {E
37f60 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ND}.**.** See al
37f70 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  so: [SQLITE_FCNT
37f80 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a  L_LOCKSTATE].*/.
37f90 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  int sqlite3_file
37fa0 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33  _control(sqlite3
37fb0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
37fc0 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20  DbName, int op, 
37fd0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
37fe0 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67  API3REF: Testing
37ff0 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 31 34   Interface {H114
38000 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a  00} <S30800>.**.
38010 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74  ** The sqlite3_t
38020 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e  est_control() in
38030 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
38040 74 6f 20 72 65 61 64 20 6f 75 74 20 69 6e 74 65  to read out inte
38050 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66  rnal.** state of
38060 20 53 51 4c 69 74 65 20 61 6e 64 20 74 6f 20 69   SQLite and to i
38070 6e 6a 65 63 74 20 66 61 75 6c 74 73 20 69 6e 74  nject faults int
38080 6f 20 53 51 4c 69 74 65 20 66 6f 72 20 74 65 73  o SQLite for tes
38090 74 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73  ting.** purposes
380a0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
380b0 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 65  ameter is an ope
380c0 72 61 74 69 6f 6e 20 63 6f 64 65 20 74 68 61 74  ration code that
380d0 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74   determines.** t
380e0 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69  he number, meani
380f0 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61 74 69 6f  ng, and operatio
38100 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73 65 71 75  n of all subsequ
38110 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  ent parameters..
38120 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
38130 66 61 63 65 20 69 73 20 6e 6f 74 20 66 6f 72 20  face is not for 
38140 75 73 65 20 62 79 20 61 70 70 6c 69 63 61 74 69  use by applicati
38150 6f 6e 73 2e 20 20 49 74 20 65 78 69 73 74 73 20  ons.  It exists 
38160 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65  solely.** for ve
38170 72 69 66 79 69 6e 67 20 74 68 65 20 63 6f 72 72  rifying the corr
38180 65 63 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  ect operation of
38190 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
381a0 61 72 79 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a  ary.  Depending.
381b0 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20 53 51  ** on how the SQ
381c0 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69 73 20  Lite library is 
381d0 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73 20 69  compiled, this i
381e0 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 6e  nterface might n
381f0 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20  ot exist..**.** 
38200 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
38210 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64  he operation cod
38220 65 73 2c 20 74 68 65 69 72 20 6d 65 61 6e 69 6e  es, their meanin
38230 67 73 2c 20 74 68 65 20 70 61 72 61 6d 65 74 65  gs, the paramete
38240 72 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c  rs.** they take,
38250 20 61 6e 64 20 77 68 61 74 20 74 68 65 79 20 64   and what they d
38260 6f 20 61 72 65 20 61 6c 6c 20 73 75 62 6a 65 63  o are all subjec
38270 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
38280 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55  out notice..** U
38290 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68  nlike most of th
382a0 65 20 53 51 4c 69 74 65 20 41 50 49 2c 20 74 68  e SQLite API, th
382b0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e  is function is n
382c0 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
382d0 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e 73  .** operate cons
382e0 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e  istently from on
382f0 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
38300 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71   next..*/.int sq
38310 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72  lite3_test_contr
38320 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  ol(int op, ...);
38330 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38340 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66  : Testing Interf
38350 61 63 65 20 4f 70 65 72 61 74 69 6f 6e 20 43 6f  ace Operation Co
38360 64 65 73 20 7b 48 31 31 34 31 30 7d 20 3c 48 31  des {H11410} <H1
38370 31 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  1400>.**.** Thes
38380 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
38390 74 68 65 20 76 61 6c 69 64 20 6f 70 65 72 61 74  the valid operat
383a0 69 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d 65 74  ion code paramet
383b0 65 72 73 20 75 73 65 64 0a 2a 2a 20 61 73 20 74  ers used.** as t
383c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
383d0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 65  t to [sqlite3_te
383e0 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a  st_control()]..*
383f0 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61 72 61 6d  *.** These param
38400 65 74 65 72 73 20 61 6e 64 20 74 68 65 69 72 20  eters and their 
38410 6d 65 61 6e 69 6e 67 73 20 61 72 65 20 73 75 62  meanings are sub
38420 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 0a 2a  ject to change.*
38430 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65  * without notice
38440 2e 20 20 54 68 65 73 65 20 76 61 6c 75 65 73 20  .  These values 
38450 61 72 65 20 66 6f 72 20 74 65 73 74 69 6e 67 20  are for testing 
38460 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a  purposes only..*
38470 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
38480 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 61 6e  hould not use an
38490 79 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  y of these param
384a0 65 74 65 72 73 20 6f 72 20 74 68 65 0a 2a 2a 20  eters or the.** 
384b0 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f  [sqlite3_test_co
384c0 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
384d0 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
384e0 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50  QLITE_TESTCTRL_P
384f0 52 4e 47 5f 53 41 56 45 20 20 20 20 20 20 20 20  RNG_SAVE        
38500 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
38510 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52  e SQLITE_TESTCTR
38520 4c 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45 20 20  L_PRNG_RESTORE  
38530 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
38540 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54  fine SQLITE_TEST
38550 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45 54 20  CTRL_PRNG_RESET 
38560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
38570 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
38580 45 53 54 43 54 52 4c 5f 42 49 54 56 45 43 5f 54  ESTCTRL_BITVEC_T
38590 45 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20  EST             
385a0 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
385b0 45 5f 54 45 53 54 43 54 52 4c 5f 46 41 55 4c 54  E_TESTCTRL_FAULT
385c0 5f 49 4e 53 54 41 4c 4c 20 20 20 20 20 20 20 20  _INSTALL        
385d0 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
385e0 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 45  LITE_TESTCTRL_BE
385f0 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b  NIGN_MALLOC_HOOK
38600 53 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65  S     10.#define
38610 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
38620 5f 50 45 4e 44 49 4e 47 5f 42 59 54 45 20 20 20  _PENDING_BYTE   
38630 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66           11.#def
38640 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
38650 54 52 4c 5f 41 53 53 45 52 54 20 20 20 20 20 20  TRL_ASSERT      
38660 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23              12.#
38670 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
38680 53 54 43 54 52 4c 5f 41 4c 57 41 59 53 20 20 20  STCTRL_ALWAYS   
38690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
386a0 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
386b0 5f 54 45 53 54 43 54 52 4c 5f 52 45 53 45 52 56  _TESTCTRL_RESERV
386c0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
386d0 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    14../*.** CAPI
386e0 33 52 45 46 3a 20 53 51 4c 69 74 65 20 52 75 6e  3REF: SQLite Run
386f0 74 69 6d 65 20 53 74 61 74 75 73 20 7b 48 31 37  time Status {H17
38700 32 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a  200} <S60200>.**
38710 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
38720 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
38730 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  ce is used to re
38740 74 72 69 65 76 65 20 72 75 6e 74 69 6d 65 20 73  trieve runtime s
38750 74 61 74 75 73 20 69 6e 66 6f 72 6d 61 74 69 6f  tatus informatio
38760 6e 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 70  n.** about the p
38770 72 65 66 6f 72 6d 61 6e 63 65 20 6f 66 20 53 51  reformance of SQ
38780 4c 69 74 65 2c 20 61 6e 64 20 6f 70 74 69 6f 6e  Lite, and option
38790 61 6c 6c 79 20 74 6f 20 72 65 73 65 74 20 76 61  ally to reset va
387a0 72 69 6f 75 73 0a 2a 2a 20 68 69 67 68 77 61 74  rious.** highwat
387b0 65 72 20 6d 61 72 6b 73 2e 20 20 54 68 65 20 66  er marks.  The f
387c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
387d0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
387e0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 70 65 63   for.** the spec
387f0 69 66 69 63 20 70 61 72 61 6d 65 74 65 72 20 74  ific parameter t
38800 6f 20 6d 65 61 73 75 72 65 2e 20 20 52 65 63 6f  o measure.  Reco
38810 67 6e 69 7a 65 64 20 69 6e 74 65 67 65 72 20 63  gnized integer c
38820 6f 64 65 73 0a 2a 2a 20 61 72 65 20 6f 66 20 74  odes.** are of t
38830 68 65 20 66 6f 72 6d 20 5b 53 51 4c 49 54 45 5f  he form [SQLITE_
38840 53 54 41 54 55 53 5f